checkRenderingUsageSpecialization requires that a RenderingUsage specialize the base
RenderingUsage Views::rendering (see 9.2.19.2.7 ).
need Views::renderings (with an "s")
in
interfaces.sysml
end port source: Port :>> BinaryConnection::source;
end port target: Port :>> BinaryConnection::target;
but 9.2.7.2.1 BinaryInterface has
source : Port [0..*]
{redefines source}target : Port
{redefines target}so one of these sources is wrong
The sentence: "ReferenceSubsetting has the same semantics as Subsetting, but the referenceFeature may have a special purpose relative to the referencingFeature." has an incorrect name for "referencedFeature", it instead uses "referenceFeature" which does not exist. Change "referenceFeature" to "referencedFeature".
Statements about “deleting” data versions does not communicate the intent. DataVersions are immutable and should not be “deleted”. If the DataVersion for the deletion of an identity were to be deleted, there would be no record of the delete, and merge could not work.
In 7.1.2 it is stated: “DataVersion.identity is unique among records listed in commit.versionedData and in Commit.change”
Therefore, there cannot be a conflicting DataVersion for the same identity in the same commit, the deleting DataVersion must remain in the change set and can’t be “deleted”. The delete should not impact any previous commit, so no DataVersions should be deleted. However, the deleting DataVersion must not be in the derived “versionedData” set.
The other consideration is the deletion of incoming references, as documented in SYSMOAS_-82. We suggest those constraints be removed until we have full constraint propagation in the API to ensure model consistency – it is an expensive operation that could break the model.
Based on this issue and in SYSMOAS_-82. Clearer wording should be provided for “3) Deleting data” in table 3. Suggested wording is:
3) Deleting Data - Commit.change should include a DataVersion record with DataVersion.payload not provided, thereby indicating deletion of DataIdentity in the new commit. DataVersion.identity should be populated with the DataIdentity that will be deleted in the new commit. When a DataIdentity is deleted in a commit, the DataVersion for that identity shall not be included in the derived versionedData relationship for that commit.
Within ProjectDataVersioningService PIM-level service specifications createCommit service Element deletion rules state the following:
When a DataIdentity is deleted in a commit, all its versions (DataVersion) are also deleted, and any references from other DataIdentity are also removed to maintain data integrity. In addition, for Element Data (KerML), deletion of an Element must also result in deletion of incoming Relationships.
This seems to be model-breaking, especially in cases of ownership-based Relationships (e.g. OwningMembership, FeatureMembership). Example:
Namespace – (OwningMembership Relationship) --> Package packA – (OwningMembership Relationship) --> PortDefinition portA.
When deleting Package packA, according to the rule described, an incoming OwningMembership Relationship should be deleted as well. However, the outgoing OwningMembership Relationship pointing to PortDefinition portA would remain to exist in the model leaving portA floating without any owner (OwningMembership Relationship has no source, it has been deleted).
Simply deleting outgoing Relationships in addition to incoming ones would also not help in this case, as the PortDefinition portA would also remain without any owner in the model.
We need to take a closer look into various Relationship kinds and their semantics in order not to break the model when manipulating via API services.
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?
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 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
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?
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 Branches can have the same head (Commit) … need multiplicity change
for example to start them off with the same set of elements
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
{readOnly}... 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
{ordered}... 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
{ordered}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
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:
{protocol}://{serverIRI}/projects/{projectId}/commits/{commitId}/elements/{elementId}{protocol}://
{serverIRI}/projects/
{projectId}/commits/
{commitId}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
{readOnly, id}also adding
{id}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."
The goal of this issue is to develop conformance test suite for the Diff and Merge endpoints in the REST/HTTP PSM. This includes the following endpoints:
1. GET /projects/
/branches/
{targetBranchId}/merge
Other details:
1. Tests should be defined for each endpoint individually.
2. Both positive and negative scenarios should be tested for each endpoint.
3. Each test must include setup, test, and tear down steps.
4. Tests will be written in Java using the JUnit framework (widely adopted).
The goal of this issue is to develop conformance test suite for the Meta endpoints in the REST/HTTP PSM. This includes the following endpoints:
1. GET /meta/datatypes
2. GET /meta/datatypes/
Other details:
1. Tests should be defined for each endpoint individually.
2. Both positive and negative scenarios should be tested for each endpoint.
3. Each test must include setup, test, and tear down steps.
4. Tests will be written in Java using the JUnit framework (widely adopted).
The goal of this issue is to develop conformance test suite for the Query endpoints in the REST/HTTP PSM. This includes the following endpoints:
1. GET /projects/
{projectId}/queries/
{queryId}5. DELETE /projects/
{projectId}/queries/
{queryId}/results
7. GET /projects/
/queries/query-results
Other details:
1. Tests should be defined for each endpoint individually.
2. Both positive and negative scenarios should be tested for each endpoint.
3. Each test must include setup, test, and tear down steps.
4. Tests will be written in Java using the JUnit framework (widely adopted).
The goal of this issue is to develop conformance test suite for the Tag endpoints in the REST/HTTP PSM. This includes the following endpoints:
1. GET /projects/
{projectId}/tags/
{tagId}Other details:
1. Tests should be defined for each endpoint individually.
2. Both positive and negative scenarios should be tested for each endpoint.
3. Each test must include setup, test, and tear down steps.
4. Tests will be written in Java using the JUnit framework (widely adopted).
The goal of this issue is to develop conformance test suite for the Branch endpoints in the REST/HTTP PSM. This includes the following endpoints:
1. GET /projects/
{projectId}/branches/
{branchId}Other details:
1. Tests should be defined for each endpoint individually.
2. Both positive and negative scenarios should be tested for each endpoint.
3. Each test must include setup, test, and tear down steps.
4. Tests will be written in Java using the JUnit framework (widely adopted).
The goal of this issue is to develop conformance test suite for the Element and Relationship endpoints in the REST/HTTP PSM. This includes the following endpoints:
1. GET /projects/
{projectId}/commits/{commitId}/commits/
{commitId}/elements/{elementId}/roots
4. GET /projects/
/commits/
{commitId}/elements/
{relatedElementId}/relationships
Other details:
1. Tests should be defined for each endpoint individually.
2. Both positive and negative scenarios should be tested for each endpoint.
3. Each test must include setup, test, and tear down steps.
4. Tests will be written in Java using the JUnit framework (widely adopted).
Description - The goal of this issue is to develop conformance test suite for the Commit endpoints in the REST/HTTP PSM. This includes the following endpoints:
1. GET /projects/
{projectId}/commits/
{commitId}/changes
5. GET /projects/
/commits/
{commitId}/changes/
{changeId}Other details:
1. Tests should be defined for each endpoint individually.
2. Both positive and negative scenarios should be tested for each endpoint.
3. Each test must include setup, test, and tear down steps.
4. Tests will be written in Java using the JUnit framework (widely adopted).
Description - The goal of this issue is to develop conformance test suite for Project endpoints in the REST/HTTP PSM. This includes the following endpoints:
1. GET /projects
2. POST /projects
3. GET /projects/
5. DELETE /projects/
{projectId}Other details:
1. Tests should be defined for each endpoint individually.
2. Both positive and negative scenarios should be tested for each endpoint.
3. Each test must include setup, test, and tear down steps.
4. Tests will be written in Java using the JUnit framework (widely adopted).
The POST projects/
{projectId}/commits endpoint in the OpenAPI spec for REST/HTTP PSM includes examples for creating elements (ElementCommitRequest), relationships (RelationshipCommitRequest), project usages (ProjectUsageCommitRequest), and others. See the attached screenshot. There is also an example (DeleteCommitRequest) that shows the commit request body when elements are to be deleted.
It will help to add specific examples (as below) that provide details of Commit.change when elements are to be created, updated, or deleted.
The goal of this task is to develop conformance test cases for the OSLC PSM of the Systems Modeling API and Services. Annex A of the specification includes Conformance Test Suite for the PIM of the API & Services. API & Services Providers and Consumers will generally conform to the individual PSMs, even though PIM-level conformance is allowed. See Section 2 (Conformance) for details. Hence, the specification should provide a Conformance Test Suite for the OSLC PSM.
The mapping table from the PIM API model in sub-clause 8.2.3 to the OSLC PSM Resource mapping is missing rows for ExternalData and ExternalRelationship.
The current requirements for Derived Property conformance (including the changes accepted in https://issues.omg.org/browse/SYSMOAS_-102 ) are too narrow.
The Query model in PIM, specifically PrimitiveConstraint entity has value attribute data type as String [ 1..* ].
However, the PrimitiveConstraint's value attribute in REST/HTTP PSM JSON schema is not typed as Array, causing inconsistency between PIM and PSM models.
The value data type in both Query PIM and PSM should be an array.
Similarly to ProjectUsage, ExternalRelationship inherits from Data, hence PIM level operation definitions should be consistent for both. At the moment PIM level ExternalRelationshipService group is lacking operations for ExternalRelationship creation and deletion when compared to ProjectUsageServices, hence:
We shall codify an additional invariant that ensures Commit timestamps increase monotonically, i.e. past commits have a strictly older timestamp.
Reasoning:
https://www.omg.org/spec/SystemsModelingAPI/20240801/OSLC-Domain-Model.zip, needs updated vocabulary and constraints files for KerML and SysML:
The vocabulary terms updates include:
The resource shape constraint updates include:
The OSLC artifacts for the current abstract syntax, as well as the script to update the artifacts, are available as open source here: https://github.com/oslc-op/oslc-specs/tree/master/specs/sysml.
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
In section 7.1.2 - the Data Versioning API Model, versionedData is a derived relationship. The spec does not specify what/how it is derived from.
Follow-up from https://issues.omg.org/browse/SYSMOAS_-83 and specifically the comment https://issues.omg.org/browse/SYSMOAS_-86?focusedCommentId=26800&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-26800 by Mr. Hans Peter de Koning
Two of the Service interfaces, namely ElementNavigationService and ExternalRelationshipService, are entirely read only, and thus are not affected by the resolution of https://issues.omg.org/browse/SYSMOAS_-83 - they work with read only API providers as is.
However, as Mr. Hans Peter de Koning argues, we should treat them the same way as all the other Service interfaces. Even though this is not useful at the moment, there are two good reasons to extend the change:
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.
Data Version record is associated with up to one (0..1) Data Identity record, this is wrong it is multiplicity of 1
the standard should specify how the commits (and previousCommit(s) ) are transverse to get all the elements
The API PIM specification has a Record entity with humanIdentifier attribute. Commit entity inherits from Record, therefore it is expected for humanIdentifier attribute to exist in Commit entity as well. This is not the case at the moment when looking at the API JSON schema.
humanIdentifier is crucial for tool vendors to be able to relate commit UUIDs to version identifiers that are specific to the different versioning schemas used by different tool vendors.
The spec says: "DataVersion.identity should be populated with the DataIdentity that will be deleted in the new commit. When a DataIdentity is deleted in a commit, all its versions (DataVersion) are also deleted,"
This sounds wrong - presumably DataVersions referenced by earlier Commits need to be maintained. This does seem to be the way that the reference implementation behaves.
Summary of rationale for SYSMOAS_-83 (Read-only API providers)
The issue SYSMOAS_-83 (https://issues.omg.org/browse/SYSMOAS_-83) put forth a good suggestion on Conformance levels. A summary of that suggestion and its purpose is stated below.
API and Services Conformances, as specified in section 2 of the specification, are directly based on individual services and require that all operations (get/create/update/delete) for the given service be implemented for a service provider to claim conformance to that service. For example, ProjectService Conformance states the following.
ProjectService Conformance - A Service Provider must implement all the operations in the ProjectService, and demonstrate that the implementation successfully passes all the ProjectService Conformance Test Cases (see A.1) and Cross-Cutting Conformance Test Cases (see A.7).
A digital engineering tool, such as a Requirements management tool or a Product Lifecycle Management (PLM) platform, may expose some of its data using services defined in this standard (Systems Modeling API and Services 1.0) using only the get operations. For example, a Requirements management tool may implement the get operations in ProjectService and ElementNavigationService to fetch requirement projects and requirement structures. Similarly, a PLM platform may implement the same to fetch hardware projects and part BOMs. However, these implementations would be non-conformant to both the ProjectService and ElementNavigationService since they would only implement the get operations and not the create/update/delete (data mutation operations).
Summary of work items for SYSMOAS_-83 (Read-only API providers)
SYSMOAS_-83 also suggested work items (included in its description) that can be summarized as below.
1. Identify get operations from mutation operations (create/update/delete) by using the 'query' UML modifier on those operations.
2. Define Read-level and Read-Write Conformance levels for each service so that non-SysML digital engineering tools that make their data available using get operations can claim Read-level conformance.
Problem with proposal SYSMOAS_-86 for SYSMOAS_-83
The proposal SYSMOAS_-86 for issue SYSMOAS_-83 took an incorrect step with major change impacts that was NOT part of the core work items in SYSMOAS_-83 and also summarized above.
Instead of limiting the change to splitting the Conformance levels for each service in section 2 for Read-Only and Read-Write Conformance, the proposal also split the individial PIM services. A new supertype service was proposed for each PIM service with get operations, e.g. ProjectServiceReadOnly with get operations, inherited by ProjectService that will also include the mutation (create/update/delete) operations.
This proposal of splitting the PIM services was not necessary to achieve the goal of SYSMOAS_-83 and has a major change impact on this specification, as described below:
1. It was not necessary to split the PIM services. Splitting of the Conformance levels in Section 2 and stating that Read-Only Conformance can be achieved by implementing the get operations (also marked by 'query' UML modifier) in each service was sufficient to achieve the original aim. Only the conformance test suite in Appendix A would have to be refactored. No PIM level services, or PSM services/endpoints, or PIM -> PSM mappings would have been affected.
2. Splitting each PIM service also impacts the mapping from PIM -> PSM for both REST/HTTP PSM and OSLC PSM. The mapping tables have to be redone, and the PSM level service groups may have to be modified. For example, GET endpoints in the REST/HTTP PSM may require to be separated from POST/PUT/DELETE. The extent of this change is significant and requires a lot more time to investigate and plan even before affecting the change. Given that FTF2 was closing in August when the proposal was approved, it was infeasible from the start in addition to being unncessary. This is true even with the new Nov 2024 deadline for submission.
3. In the future, as this standard and the service providers evolve, we may need to define new conformance levels or refactor existing conformance levels. Changes in the conformance levels should not require us to rearchitect the design of the PIM services which then subsequently impacts the PSM services and the PIM -> PSM mappings.
4. It is also not recommended to name services with "read" or "write". This is done at the operation level. A service is a grouping of operations related to an entity, and should remain so.
Solution being proposed in this issue
This issue is being opened to correctly implement the core work items of SYSMOAS_-83 and to rollback the PIM service splitting step in proposal SYSMOAS_-86. A draft proposal will be forumated in the comment of this issue, and following a discussion in the FTF2 meeting, a formal proposal will be created an attached to this issue.
in the description of getCommitChange and diffCommits they reference an optional argument changeTypes, which doesn't appear in figure 10
says in the standard "Branches are immutable", no they are mutable... can change the head subsequently
it is unclear if queryConformace implies derivedProperties conformance. In other words, does the query service provider need to support derived properties or not.
OSLC API Resource Shapes and Vocabulary (both for KerML and SysML2) get automatically generated from respective Ecore metamodels, which leads to OCL expressions ending up as part of documentation in <rdfs:comment> properties. This makes the generated vocabularies and shapes super ugly and hard to read, e.g.:
<rdf:Description rdf:about="https://www.omg.org/spec/SysML/20230201/vocab#Expression"> <rdfs:comment><p>An Expression is a Step that is typed by a Function. An Expression that also has a Function as its <code>featuringType</code> is a computational step within that Function. An Expression always has a single <code>result</code> parameter, which redefines the <code>result</code> parameter of its defining <code>function</code>. This allows Expressions to be interconnected in tree structures, in which inputs to each Expression in the tree are determined as the results of other Expressions in the tree.</p> isModelLevelEvaluable = modelLevelEvaluable(Set(Element){}) specializesFromLibrary("Performances::evaluations") owningMembership <> null and owningMembership.oclIsKindOf(FeatureValue) implies let featureWithValue : Feature = owningMembership.oclAsType(FeatureValue).featureWithValue in featuringType = featureWithValue.featuringType ownedMembership.selectByKind(ResultExpressionMembership)-> forAll(mem | ownedFeature.selectByKind(BindingConnector)-> exists(binding | binding.relatedFeature->includes(result) and binding.relatedFeature->includes(mem.ownedResultExpression.result)))</rdfs:comment>
Prior OSLC artifact generation we need to figure out how to distinguish between normative documentation of metamodel objects (eClassifiers and eOperations) vs their OCL expressions in the original Ecore files.
Since OSLC vocabulary gets generated automatically from SysML2 metamodel, it would make sense for it to include typing hierarchy (eSuperTypes of eClassifiers --> rdfs:subClassOf statements) which would make the vocabulary more semantically “rich” and enable some RDFS reasoning on top of it.
The beta spec should provide details on deleting a project that has commits with data.
ProjectService in the PIM includes an operation "deleteProject" to delete a project. An equivalent endpoint is available in the REST/HTTP PSM (DELETE /projects/
{projectId}).
However the specification should provide details, including recommended practices on what happens to the contents of a project and project usages when a project is deleted.
Note that authorization (permissions) are outside the scope of the specification but related to this action.
OSLC-OP is working on publishing an OASIS multi-part specification:
OSLC Systems Modeling Language Version 2.0. Part 1: Specification
OSLC Systems Modeling Language Version 2.0. Part 2: Vocabulary
OSLC Systems Modeling Language Version 2.0. Part 3: Constraints
OSLC Systems Modeling Language Version 2.0. Part 4: Machine Readable Vocabulary Terms
OSLC Systems Modeling Language Version 2.0. Part 4: Machine Readable Constraints
This is the same as other OSLC servers and RDF vocabularies, and that Systems Modeling Application Programming Interface (API) and Services can reference these documents instead of directly including copies in the OMG specification zip file. The vocabulary and constraints would also be published on open-services.net and accessed using the namespace URL.
The Part 1: Specification describes the conformance clauses an OSLC SysML server meets. It references OMG Systems Modeling Language. https://www.omg.org/spec/SysML/ for all information on SysML. It is a standard for an OSLC server supporting SysML, with vocabulary terms providing an RDF representation of the normative OMG SysML v2 XMI.
See file:///Users/jamsden/Developer/OSLC/oslc-op/oslc-specs/specs/am/architecture-management-spec.html which is a similar specification following the same pattern.
OASIS haw publish OSLC Systems Modeling Language v2.0 PSD01 (Project Specification Draft, revision 01). You can access the files at:
OSLC Systems Modeling Language Version 2.0
Project Specification Draft 01
25 April 2024
OSLC Systems Modeling Language Version 2.0. Part 1: Specification.
https://docs.oasis-open-projects.org/oslc-op/sysml/v2.0/psd01/sysml-spec.html
https://docs.oasis-open-projects.org/oslc-op/sysml/v2.0/psd01/sysml-spec.pdf
OSLC Systems Modeling Language Version 2.0. Part 2: Vocabulary.
https://docs.oasis-open-projects.org/oslc-op/sysml/v2.0/psd01/sysml-vocab.html
https://docs.oasis-open-projects.org/oslc-op/sysml/v2.0/psd01/sysml-vocab.pdf
OSLC Systems Modeling Language Version 2.0. Part 3: Constraints.
https://docs.oasis-open-projects.org/oslc-op/sysml/v2.0/psd01/sysml-shapes.html
https://docs.oasis-open-projects.org/oslc-op/sysml/v2.0/psd01/sysml-shapes.pdf
OSLC Systems Modeling Language Version 2.0. Part 4: Machine Readable Vocabulary Terms. https://docs.oasis-open-projects.org/oslc-op/sysml/v2.0/psd01/sysml-vocab.ttl
OSLC Systems Modeling Language Version 2.0. Part 5: Machine Readable Constraints. https://docs.oasis-open-projects.org/oslc-op/sysml/v2.0/psd01/sysml-shapes.ttl
This namespace will be published at http://open-services.net/ns and will provide content negotiation for tools to be able to access the vocabulary and constraints in various RDF resource representations.
All OSLC domain specifications use an open-services.net namespace, e.g., http://open-services.net/ns/am#. The same namespace is used for vocabulary terms and shapes for consistency, and to support navigation to specific sections in the vocabulary and constraints documents for elements of the namespace. The namespaces URLs also provide machine readable access to the RDF resources for use by tools.
RDF namespaces can include version identifiers, but for OSLC integration standards, the OSLC-OP recommends against inclusion of version identifiers as that introduces integration incompatibilities as the standards evolve.
The section OSLC 3.0 API section in Systems Modeling Application Programming Interface (API) and Services will need to be updated to refer to the correct namespace.
This is perhaps not an issue and may require no action other than acknowledging that it is being done, and isn’t formally following KerML semantics.
If this is not acceptable, then we can generate the OSLC SysML v2 vocabulary to import and specialize KerML. That would add some additional work and redundancy, but could be done.
If this is adopted, then there is no reason for the OSLC 3.0 API to define the KerML vocabulary and constraints, hence the reason it is not include in #1 above.
Right now, the standard assumes repositories that provide any of the listed API services to implement all operations of these services, both the read only ones and the mutating ones. I believe we should have at least vocabulary in the standard to describe and recognize the kind of partial compliance with a given API Service where only the read-only operations of the Service are actually provided.
*Reasoning.* In order for a service to claim SysML compliance, it must implement some combination of the 6 existing API services defined in the standard. Most of which prescribe mutation operations such as createProject(), etc. but especially and primarily createCommit(), that make little sense to implement if the single source of truth is a data format other than SysML (or the textual format of SysML), and the SysML format is merely a derived view of the data.
*Example.* An off-the-shelf requirement managements system might not be willing to try and implement arbitrary SysML model mutation commands (especially pertaining to non-requirement stuff), and on the other hand creating requirements entries might require data fields that are not mandatorily written via the SysML API - at any rate this is a bad match.
*Core proposal.* It would make a lot of sense in these use cases if the standard talked about an officially recognized way for these services to claim that they implement some Services of the SysML API - but only the read-only operations. This does not mean that the projects would be immutable, just that they are to be modified through a means other than the SysML API.
*Clarification.* This request is not about user-specific access permissions. Even in the current version of the standard, any SysML v2 repository may in principle be configured so that certain users are forbidden from executing operations that manipulate state, there will still be other users that are authorized to execute them. In contrast, the proposed change would introduce repositories where (certain types of) mutation of state is simply not accomplished through SysML v2 API, but through other means.
*Impact on testability.* Repositories that provide the read-only form of one of the Services should still comply with the semantics and constraints of the read-only operations exposed by the Service. However, since the state of such repositories is not (fully) controllable via the SysML v2 API, this conformance relationship may not be possible to test via the Conformance Test Suite as is. Providers of such repository technologies are expected to demonstrate conformance via modified test cases, adapted to set up and influence repository state by means appropriate for the specific technology, with effects matching the original conformance test as closely as possible.
*Work items.* I propose to elaborate in detail the following changes to the standard:
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.
The goal of this issue is to develop conformance test suite for the Query endpoints in the REST/HTTP PSM. This includes the following endpoints:
1. GET /projects/
{projectId}/queries/
{queryId}5. DELETE /projects/
{projectId}/queries/
{queryId}/results
7. GET /projects/
/queries/query-results
Other details:
1. Tests should be defined for each endpoint individually.
2. Both positive and negative scenarios should be tested for each endpoint.
3. Each test must include setup, test, and tear down steps.
4. Tests will be written in Java using the JUnit framework (widely adopted).
The goal of this issue is to develop conformance test suite for the Tag endpoints in the REST/HTTP PSM. This includes the following endpoints:
1. GET /projects/
{projectId}/tags/
{tagId}Other details:
1. Tests should be defined for each endpoint individually.
2. Both positive and negative scenarios should be tested for each endpoint.
3. Each test must include setup, test, and tear down steps.
4. Tests will be written in Java using the JUnit framework (widely adopted).
The goal of this issue is to develop conformance test suite for the Diff and Merge endpoints in the REST/HTTP PSM. This includes the following endpoints:
1. GET /projects/
/branches/
{targetBranchId}/merge
Other details:
1. Tests should be defined for each endpoint individually.
2. Both positive and negative scenarios should be tested for each endpoint.
3. Each test must include setup, test, and tear down steps.
4. Tests will be written in Java using the JUnit framework (widely adopted).
The goal of this issue is to develop conformance test suite for the Meta endpoints in the REST/HTTP PSM. This includes the following endpoints:
1. GET /meta/datatypes
2. GET /meta/datatypes/
Other details:
1. Tests should be defined for each endpoint individually.
2. Both positive and negative scenarios should be tested for each endpoint.
3. Each test must include setup, test, and tear down steps.
4. Tests will be written in Java using the JUnit framework (widely adopted).
The goal of this issue is to develop conformance test suite for the Element and Relationship endpoints in the REST/HTTP PSM. This includes the following endpoints:
1. GET /projects/
{projectId}/commits/{commitId}/commits/
{commitId}/elements/{elementId}/roots
4. GET /projects/
/commits/
{commitId}/elements/
{relatedElementId}/relationships
Other details:
1. Tests should be defined for each endpoint individually.
2. Both positive and negative scenarios should be tested for each endpoint.
3. Each test must include setup, test, and tear down steps.
4. Tests will be written in Java using the JUnit framework (widely adopted).
The goal of this issue is to develop conformance test suite for the Branch endpoints in the REST/HTTP PSM. This includes the following endpoints:
1. GET /projects/
{projectId}/branches/
{branchId}Other details:
1. Tests should be defined for each endpoint individually.
2. Both positive and negative scenarios should be tested for each endpoint.
3. Each test must include setup, test, and tear down steps.
4. Tests will be written in Java using the JUnit framework (widely adopted).
Description - The goal of this issue is to develop conformance test suite for the Commit endpoints in the REST/HTTP PSM. This includes the following endpoints:
1. GET /projects/
{projectId}/commits/
{commitId}/changes
5. GET /projects/
/commits/
{commitId}/changes/
{changeId}Other details:
1. Tests should be defined for each endpoint individually.
2. Both positive and negative scenarios should be tested for each endpoint.
3. Each test must include setup, test, and tear down steps.
4. Tests will be written in Java using the JUnit framework (widely adopted).
Description - The goal of this issue is to develop conformance test suite for Project endpoints in the REST/HTTP PSM. This includes the following endpoints:
1. GET /projects
2. POST /projects
3. GET /projects/
5. DELETE /projects/
{projectId}Other details:
1. Tests should be defined for each endpoint individually.
2. Both positive and negative scenarios should be tested for each endpoint.
3. Each test must include setup, test, and tear down steps.
4. Tests will be written in Java using the JUnit framework (widely adopted).
The API PIM specification has a Record entity with humanIdentifier attribute. Commit entity inherits from Record, therefore it is expected for humanIdentifier attribute to exist in Commit entity as well. This is not the case at the moment when looking at the API JSON schema.
humanIdentifier is crucial for tool vendors to be able to relate commit UUIDs to version identifiers that are specific to the different versioning schemas used by different tool vendors.
Since OSLC vocabulary gets generated automatically from SysML2 metamodel, it would make sense for it to include typing hierarchy (eSuperTypes of eClassifiers --> rdfs:subClassOf statements) which would make the vocabulary more semantically “rich” and enable some RDFS reasoning on top of it.
OSLC API Resource Shapes and Vocabulary (both for KerML and SysML2) get automatically generated from respective Ecore metamodels, which leads to OCL expressions ending up as part of documentation in <rdfs:comment> properties. This makes the generated vocabularies and shapes super ugly and hard to read, e.g.:
<rdf:Description rdf:about="https://www.omg.org/spec/SysML/20230201/vocab#Expression"> <rdfs:comment><p>An Expression is a Step that is typed by a Function. An Expression that also has a Function as its <code>featuringType</code> is a computational step within that Function. An Expression always has a single <code>result</code> parameter, which redefines the <code>result</code> parameter of its defining <code>function</code>. This allows Expressions to be interconnected in tree structures, in which inputs to each Expression in the tree are determined as the results of other Expressions in the tree.</p> isModelLevelEvaluable = modelLevelEvaluable(Set(Element){}) specializesFromLibrary("Performances::evaluations") owningMembership <> null and owningMembership.oclIsKindOf(FeatureValue) implies let featureWithValue : Feature = owningMembership.oclAsType(FeatureValue).featureWithValue in featuringType = featureWithValue.featuringType ownedMembership.selectByKind(ResultExpressionMembership)-> forAll(mem | ownedFeature.selectByKind(BindingConnector)-> exists(binding | binding.relatedFeature->includes(result) and binding.relatedFeature->includes(mem.ownedResultExpression.result)))</rdfs:comment>
Prior OSLC artifact generation we need to figure out how to distinguish between normative documentation of metamodel objects (eClassifiers and eOperations) vs their OCL expressions in the original Ecore files.
it is unclear if queryConformace implies derivedProperties conformance. In other words, does the query service provider need to support derived properties or not.
The POST projects/
{projectId}/commits endpoint in the OpenAPI spec for REST/HTTP PSM includes examples for creating elements (ElementCommitRequest), relationships (RelationshipCommitRequest), project usages (ProjectUsageCommitRequest), and others. See the attached screenshot. There is also an example (DeleteCommitRequest) that shows the commit request body when elements are to be deleted.
It will help to add specific examples (as below) that provide details of Commit.change when elements are to be created, updated, or deleted.
In section 7.1.2 - the Data Versioning API Model, versionedData is a derived relationship. The spec does not specify what/how it is derived from.
The beta spec should provide details on deleting a project that has commits with data.
ProjectService in the PIM includes an operation "deleteProject" to delete a project. An equivalent endpoint is available in the REST/HTTP PSM (DELETE /projects/
{projectId}).
However the specification should provide details, including recommended practices on what happens to the contents of a project and project usages when a project is deleted.
Note that authorization (permissions) are outside the scope of the specification but related to this action.
The goal of this task is to develop conformance test cases for the OSLC PSM of the Systems Modeling API and Services. Annex A of the specification includes Conformance Test Suite for the PIM of the API & Services. API & Services Providers and Consumers will generally conform to the individual PSMs, even though PIM-level conformance is allowed. See Section 2 (Conformance) for details. Hence, the specification should provide a Conformance Test Suite for the OSLC PSM.
In the PIM, ProjectDataVersioningService.diffCommits(...) operation returns a set of differences between two commits (baseCommit and compareCommit). This includes elements added, updated, or deleted in the compareCommit compared to the baseCommit.
The set of differences returned from the diffCommits operations can be large, even though served using pagination.
In many scenarios, consumers of the API may only be interested in specific types of changes, e.g. elements added, or updated, or deleted.
Can we add an additional argument to the diffCommits operation that returns a filtered set of differences based on a change type versus all the differences.
In the PIM, ProjectDataVersioningService.getCommitChange(...) operation returns a set of changes in a given commit compared to the previous commit(s). This includes elements added, updated, or deleted in the given commit. The set of changes returned from the getCommitChange(...) operations can be large, even though served using pagination. In many scenarios, consumers of the API may only be interested in specific types of changes, e.g. elements added, or updated, or deleted.
Can we add an additional argument to the getCommitChange(...) operation that returns a filtered set of changes based on a change type versus all the changes?
The query is only described using abstract syntax. While most of the API REST commands are fairly straightforward, it is not the case for query. There needs to be a BNF production that specifies the concrete syntax for query, which is the string that would be passed in the body of the post command
The goal of this task is to develop conformance test cases for the REST/HTTP PSM of the Systems Modeling API and Services.
Annex A of the specification includes Conformance Test Suite for the PIM of the API & Services.
API & Services Providers and Consumers will generally conform to the individual PSMs, even though PIM-level conformance is allowed. See Section 2 (Conformance) for details. Hence, the specification should provide a Conformance Test Suite for the REST/HTTP PSM.
In the Project Data Versioning PIM (Sec 7.1.2, Fig. 5), the relationship between DataVersion and its payload Data is inconsistent with the representation of deletion in Commits.
As per page 71, Commit::change "is the set of DataVersion records representing Data that is created, updated, or deleted in the
Commit". This implies that Data being deleted by the Commit must be expressed as a DataVersion object somehow.
The approach followed by the JSON/RPC PSM is that the DataVersion has an identity that identifies the Data, but the payload is null. However, in the PIM, the multiplicity of DataVersion::payload does not allow it to be null. So seemingly the PIM cannot actually express a Commit that deletes things.
In the API PIM, under ElementNavigationService, there's a getElements service which is dedicated for dumping the entire model content at a given commit.
This is an overkill for a use case when only part of the model content (e.g. a package) is required to do analysis (or any other task) on.
While theoretical a workaround could be used via getRelationshipsByRelatedElement by retrieving all of the owned elements under specified owner, this would result in gazillion separate calls and would not be efficient under slower networks.
Proposal - introduce a new service getOwnedElements with an ability to collect all of the owned elements recursively under specified root or enrich getElements with optional arguments allowing to achieve the same.
Currently state machines GBNF allows for inclusion of control nodes:
fork, join, merge, final
They are not currently supported by SysML v2 state semantics and concrete syntax and need to be removed
