Flexo SysML API Dev Plan

Owned by chris delp
Last updated: Oct 22, 2024
4 min read

Objectives

  • Result - implementing an open source sysml2 server as part of flexo MMS

    • simple ReST/JSON

    • JSON LD/OSCL RDF

    • Integrated with FlexoMMS and SysML 2 ontology and/or RDF

  • Result - development pipeline for performing development and release updates

 

 

 

Plan

 

Milestone Goals

11/14/2024 - stubbed out API server implemented

12/19/2024 - Implement a basic, non-versioned “put and get” of an entire SysML

2/1/2025 - MVP for testing and review

 

Specific tasks

Decide on the programming language to be used at each stage. For Flexo, Java is preferred

Pick an API framework, one with open-api support

Finalize and validate generated OWL

Finalize and validate generated OSLC spec, including RDFS

Setup repositories and dev environment

With the open-api document in the SysML spec, use open-api tool chain, produce a “Stubbed out server” – that is a server that responds to the API calls but has no backend implementation. This can then be leveraged and refined along multiple workstreams.

Document any issues with the open-api spec to be handled by the FTF/RTF

Define & implement additional test cases with a test framework

Implement a basic, non-versioned “put and get” of an entire SysML model using generic RDF/SparQL. This implements the mapping of the the API “model content” to RDF.

Implement versioning with Flexo utilizing the above mapping.

Implement API capability for diff/merge

Implement API capability for derived relations (discussion below)

Implement API Security, TBD, Consider OpenMBE approach.

Validate the system with test cases, existing clients & benchmark performance.

 

Committers

Cory Casanave, MDS - cory-c@modeldriven.com

Ed Seidewitz, MDS - ed-s@modeldriven.com

Jason, Doris, Blake

 

 

Considerations

  • The purpose of the server is to store and retrieve SysML models based on the abstract syntax as defined in the SysML Spec.

  • The primary & initial interface to RDF repositories will utilize the open-api specification. As the project progresses, the following capabilities can be implemented in stages:

    • Generic “stubbed out” API server implementation

    • Push and retrieve full SysML-RDF models without regard to versioning – this can use generic RDF SparQL

    • Respect API versioning mapped to Flexo capabilities, which are still in pre-release.

    • Support the API capability for derived relationships

    • Support Diff/Merge

  • The current OSLC specification is not considered sufficient and has been replaced by the OASIS-OSLC team. Flexo may want to implement the OSLC interface, that will be looked at after the full API implementation.

  • We will use the same URIs between the UML/Flexo , OSLC, & API representations. There are technical and “political” considerations.

    • OSLC requires URIs that are not version-specific, this would also be preferable for Flexo. The OMG spec may also have version-specific URIs.

    • OSLC requires that the URIs be “dereferenceable”, thus if they are OMG URIs, OMG would have to host, at a minimum, the RDFS representation compatible with OSLC. Oasis typically hosts OSLC specifications with a Oasis namespace but has agreed to use the OMG namespace.

  • Besides open API and OSLC, an additional interface is possible via XMI.

  • Once we have the API and repository we can start work on UI and document generation.

  • There are issues with respect to retaining the order of lists in RDF, which are discussed below.

 

 

 

 

 

Current State

 

 

 

 

 

 

 

 

 

 

 

RDF Representation specifics

Representing ordered lists in RDF

The SysML-V2 specification defines all properties and association ends with a multiplicity >1 as ordered. This ordering is important for the proper interpretation of SysML semantics and compatibility with other representations. There is no “native” list datatype in RDF, and there are various approaches to representing ordered lists, but none of them are ideal.

The Open-API uses JSON that is not Json-LD. It will be a requirement that the ordering implied by the JSON is preserved by whichever pattern we use in RDF. If JSON-LD were to be used in the API it would not preserve order as order is not specified in the RDF semantics.

Triple Reification Option (Agreed choice)

The RDF repository must retain the ordering semantics when persisting and retrieving SysML models. We will Use triple reification and, when/if it becomes standard, RDF-Star to make an ordering “statement” about each triple defining a collection. This would have the advantage that the OWL could properly express the range of a property,  look “normal” and could be reasoned over for model validation. We would interpret the semantics of the Ordering annotation to imply the need for the reification. The consideration would be that each ordered element would take 6 triples. Also, there is no syntactic sugar for it (today) as there is with rdf:List.
The pattern would look like this:

#given

:r a SysML:Relationship.

:e a SysML:Element .

#This is the actual triple for the SysML:source property of a relationship

:r SysML:source :e .

# The following orders it with the addition of an "ordering" property defined for SysML.

:s_1 a rdf:Statement  ;

                rdf:subject :r  ;

                rdf:predicate SysML:source;

                rdf:object :e ;

                Ordering:order 1 .

Based on the current RDF-Star draft, in the Turtle syntax, it would look something like:

<< :r SysML:source :e  >> :Ordering:order 1 .

Justification: this option preserves “normal OWL” syntax & semantics with the ordering as an extension. Also, if SysML decides that not every list needs to be ordered, it could easily be removed without changing the core ontology. There will also be an annotation defining a property as ordered. If generated via OML, this ordering semantic would need to be in OML as well.