From Tim Weilkiens <tim.weilkiens@oose.de>

I got the following question from someone who does some experiments with the API:

Here is an excerpt from the SysML v2 API specification:

> For creating new Data, CommitRequest.change should include a DataVersion where DataVersion.payload includes the Data being created and DataVersion.identity is not specified.

It says that DataVersion.identity must not be specified when creating new data.

However, how can one commit new data with multiple elements that reference each other, if we cannot provide IDs to the elements that will allow each of them to be referenced from other elements via its ID?

As a side note, it has been noticed that the Juypter notebook support for SysMLv2 in the SysML release does specify the “identity” during the creation of new data, when it publishes a model via “%publish …”. This has been verified by using an HTTP sniffer to sniff the POST command that was send

Note: the PIM spec also says something similar

> (1) Creating Data - Commit.change should include a DataVersion record with DataVersion.payload populated with the Data being created. DataVersion.identity is not provided, thereby indicating that a new DataIdentity needs to be created in the new commit.

ProjectUsages are Data and so need to use the DataIdentity/DataVersion mechanism but none of this is mentioned in the descriptions of the functions. It also doesn't aay whether you can update a project usage to reference a different commit or

The argument to the function updateQuery is a query - I don't understand what this means - it also seems to be different than how updateProject works.

What happens if the resolution is that an identity is deleted?

in the description of getCommitChange and diffCommits they reference an optional argument changeTypes, which doesn't appear in figure 10

e.g. getElements( project : Project, commit : Commit ) : Element [0..*]

commit references project so you don't need both.

createProject( name : String, description : String [0..1] ) : Project

how do we create other properties of Project inherited from Record?

property is a property of Data (or its realizations)
value is a list of primitive objects, such as String, Boolean, Integer, Double, and UUID

so why are they both typed by string?

The spec says that "select is a list of properties of Data (or its realizations)" so why is it typed by string and not something stronger?

The property doesn't seem to be composite in the API

The spec says "and represents the relationship between a
KerML Element [KerML] in a provider tool or repository to ExternalData in another tool or repository." This sounds very vague given that the neither the notions repository or tool have official definitions.

The spec also says "ExternalData may be a KerML Element or a non-KerML Element." I don't see how this is significant given that access is via IRI anyway.

the spec says "• owningProject is the project that owns the given branch" - this is a redefinition of owningProject on commitReference but I don't understand why it is needed.

The spec says "usage is the set of Project Usage records representing all other Projects being used by the given Project (Project Usage.usedProject)" but I can't see this in the xmi

the spec for project says "identifiedData is a derived attribute that is the set of Data Identity records corresponding to the Data contained in the project" but this doesn't seem to exist in xmi.

The spec says "Data Version.id is set to a new, randomly generated UUID for the specific Data Version record.". This seems a bit superfluous and probably is overspecified.

createAt and deleteAt attributes don't exist in the XMI.

The spec says "Each realization of Data must implement the getId() operation that provides a valid UUID." but this doesn't seem to be the case

https://www.omg.org/spec/SystemsModelingAPI/20240801/OSLC-Domain-Model.zip, needs updated vocabulary and constraints files for KerML and SysML:

• KerML Shapes-shapes.xml
• KerML Vocabulary-vocab.xml
• SysML Shapes-shapes.xml
• SysML Vocabulary-vocab.xml

The vocabulary terms updates include:

• Use updated SysML.ecore and KerML.ecore source files for generating the vocab files.
• Add the ontology element to the vocab .ttl file.
• Generate Turtle instead of RDF/XML
• Add Apache License Version 2.0 comment headers to the .ttl files.
• Add OASIS copyright notice.
• KerML and SysML v2 Element subclass oslc_am:Resource to link SysML elements to other lifecycle resources (e.g., requirements, change requests, test cases, etc.)
• Add rdfs:isDefinedBy oalc_sysmlv2 and rdfs:label to each vocabulary terms
• Translate the EEnum enumerations to RDF, e.g., FeatureDirectionKind
  See [Defining Enumerations](file:///Users/jamsden/Developer/OSLC/oslc-op/oslc-specs/specs/core/core-vocab.html#enumerations). An EEnum would be an rdfs:Class (with label, comment and definedBy). Its enumeration literals have rdf:type of the enumeration class, and just a label.
• Add SysML subclasses in the SysML vocabulary terms
• Use the SysML v2 non-versioned namespace for the vocabulary terms: @prefix oslc_sysmlv2: <http://www.omg.org/spec/sysmlv2/2.0#> .
• Set rdfs:comment in the vocab file to be the first paragraph in the eCore description with the markup stripped out.
• Fix ShapeChecker errors

The resource shape constraint updates include:

• Used updated SysML.ecore and KerML.ecore source files for generating shapes files.
• Add the ResourceShapeConstraints element to the shapes.ttl file
• Generate Turtle intead of RDF/XML
• Add Apache License Version 2.0 comment headers to the .ttl files.
• Add OASIS copyright notice.
• Add inherited oalc_am:Resource properties to the shapes for KerML and SysML v2 Element
• Update the versioned namespace for the resource shape constraints: @prefix : <https://www.omg.org/spec/SysML/shapes/20240801#> .
• Set dcterms:description in the shapes files to the first paragraph in the eCore description (retaining the markup).
• Separate the class name prefix from the attribute name with _ for the ResourceShapes
• Add cardinality, range and valueType to shape properties.
• Fixed ShapeChecker errors

the standard should specify how the commits (and previousCommit(s) ) are transverse to get all the elements

Two Branches can have the same head (Commit) … need multiplicity change
for example to start them off with the same set of elements

since DataIdentity is in the scope of the whole project, one can have multiple Branches where this DataIdentity is created in different Commits in different branches... and deleted in different Commits in different Branches...

so these cannot be associated with the DataIdentity... DataVersion's commit is where that information must be stored...

one could however have an operation that takes a project and branch and DataIdentity... and computes the Creation and Deletion Times from this

not sure one needs scope here... how would it work?... needs documentation in the spec about its use and an example

does the standard want to deal with locking on versioning systems?

says in the standard "Branches are immutable", no they are mutable... can change the head subsequently

Data Version record is associated with up to one (0..1) Data Identity record, this is wrong it is multiplicity of 1

need OCL to specify... previousCommits must be in the same project as the Commit

Data does not need to be further refined in the standard (i.e. no need for Relationship and operations like getRelationshipsByRelatedElements)... these could be there for operations that specifically deal with KerML models...
I would suggest if doing that there should be two sections to this standard or possibly two standards... one that deals with
versioning... the other that is specific to the serialized model

I have a reworked model at https://material.elparazim.com/SysMLv2API/

"usage is the set of Project Usage records representing all other Projects being used by the given Project"… this does not work, need a particular commit for this

What does project usage mean?... I am presuming this comes from Cameo kind of idea about ProjectUsage... but what in this spec does it mean and what can one surmise about it

currently in the spec a ProjectUsage refers to a project that is also local on the system (Server)...
there needs to be a way to reference a project (external) on another server...

I have a reworked model at https://material.elparazim.com/SysMLv2API/

Head on Branch should be multiplicity 0..1 ... when Branch is first created there is no commit

Projects may have multiple DataVersions… change Multiplicity

There should be a navigation between DataVersion to DataIdentity... presumably DataVersion knows about DataIdentity but not vice-versa

Two Tags should be able to be on the same Commit… need multiplicity change

Would suggest OCL for ProjectUsage and CommitReference constraints

suggestions in model at https://material.elparazim.com/SysMLv2API/

ProjectUsage needs a derived attribute “usedProject”

“created” attribute in Project, CommitReference, Commit should be

... these are not the only ones

I have a reworked model at https://material.elparazim.com/SysMLv2API/

there needs to be a statement in the standard concerning how things are serialized...

I have reworked the model here https://material.elparazim.com/SysMLv2API/ and used two stereotypes...
<<NS>> and <<SID>> which stand for "No Serialization" and "Serialize Id (only)"
I believe this leads to a full understand of what will come when one serializing something from
the APi (also examples are given for this serialization(s))

the standard for functions should be, e.g.

getExternalRelationships(projectId:UUID, branchId:UID[0..1],commitId:UID[0..1]):ExternalRelationship[0..*]

which means if a branchId is missing use the commitId, if commitId is missing then use the head of the branchId if it is there,
otherwise, use the default Branch and its head of the project given
many of the API operations need to be specified this way to be consistent

I have a reworked model at https://material.elparazim.com/SysMLv2API/

Most of the API is over specified… as an example, getExternalRelationship has that you need to give it a Project… but you do not need a Project, you only need a ProjectId… so for this one example…
getExternalRelationships(project:Project,commit:Commit):ExternalRelationship[0..*] should be
getExternalRelationships(projectId:UID,commitId:UID):ExternalRelationship[0..*]

this would follow the Interface Segregation Principle (“no client should be forced to depend on methods it does not use”)… most of the API is over specified in this way

I have a reworked model at https://material.elparazim.com/SysMLv2API/

specification and language need to be

... this will have the same kind of semantics as
Opaque/Expression or Behavior from UML (see fig 8.2 and its description in UML 2.5.1)

Need at least one example of a specification for an ExternalRelationship...

also need to define what it means if the specification is null (i.e. presume this means that one is referring to the entire element, so this is the way one specifies that an element in a model is really a remote element from another model)... this needs to be specified

need to explain in the standard why value is 1..* (presuming because of the "in" operator, but the semantics of that is not specified)

Fig. 7 orderBy should be

Fig. 7 queries (which should be a singular, query) is an associationend… whereas in fig. 5 queries is shown as an attribute (needs to be removed in fig. 5)

1. Fig. 7, Operator and JoinOperator need to be shown as enumerations, with literal compartments

1. Fig 6 visibility is not shown on all the attributes, needs to be consistent
2. Fig 7 visibility is not shown on all the attributes, needs to be consistent

Fig 5 Project, Commit, CommitReference all have created as a attribute, But many of the examples (and some of the text have timestamp).. needs to be consistent… I like “created” as it tells one what the timestamp is for

and deleted as the other timestamp name

would suggest using either MOF or UML to show diagrams and to employ ownership dots... note that KerML is specified this way

there are some multiplicities not shown... since there is no specification in the standard about what modeling language the diagram is in... do not know how to interpret these missing multiplicities... would suggest explicitly showing all multiplicities in the diagram

the models used in the standard have the association ends wrapped so you can't see them... suggest that they be unwrapped and
shown on one line

all the standard modeling languages use the same convention as well as most modeling style guides... and so does KerML...

all attributes and association ends are singular... the fact that they can be plural is taken care of by multiplicity

would suggest this convention be followed

IRI standard is referenced, but that does not give a precise definition of how to use it, especially if one wants to be interoperable among implementations... would suggest...

Standard ProjectI IRI:

://

/projects/

/commits/

the first is for Elements and the second is for externally referenced projects

resourceIdentifier is not needed in the record (although would be interesting)... statements about that in another issue... but remove alias, humanidentifier... and description... for example DataVersion and DataIdentity does not need a description... would suggest creating a NamedRecord where name and description are added into that and have Project, Commit, CommitReference, Query specialize that

it does not specify what language these models are in... UML, SysML, KerML, SysML2, MOF?...
it makes a difference in, e.g., interpreting the multiplicities... I would suggest doing the models in MOF and making everything explicit (e.g. multiplicities)

one needs Unique IDs (UID) but not UUID (Universally Unique ID) for most things in this standard,
and would suggest that Record be changed and that it would have

id : UID

also adding

here... and make Project (which is the only thing I can see that needs a UUID)

Project
id : UUID

there is nothing in this standard specifically about SysML or KerML... which is good... I would suggest that the Scope be rewritten and the standard be called "Versioning" or something like that... there is greater use of this standard inside modeling (i.e. legacy modeling language can use this as well) as well as outside of modeling (i.e. anything that can serialized can use this standard to have versions of that serialization)... so would suggest the Scope be changed to say

"The purpose of this standard is to specify the Versioning Application Programming Interface (API) and Services that provide standard services to access, navigate, and operate on serialized elements and in particular can be used for modeling languages."