Appendix C. The Systems Modeling API
Alongside the textual notation this book teaches, the SysML v2 specification suite defines a second interchange surface: the Systems Modeling API and Services specification, a standard REST/HTTP API for programmatic access to model data. Where the textual notation is how people write and exchange models, the API is how tools do – a requirements-management system pulling coverage data, a CI job comparing two versions of a model, a dashboard tracking element counts across a programme, all without any of them parsing anyone’s source files.
This appendix explains the API as the OMG specification defines it: the concepts, why they are shaped the way they are, and what any conformant implementation gives you. It is a reference companion to the modelling chapters – you do not need any of it to write a SysML v2 model. Come here when you are ready to connect a model to your broader engineering toolchain.
Why a standard API exists
The textual notation answers “what does this model say?”; the API answers “how do tools agree on which model, at which version, says it?”. Interchange needs an identity story as much as it needs a syntax. The API specification supplies that story with four concepts:
| Concept | Description |
|---|---|
| Project | A top-level container. Every model lives inside a project. |
| Branch | A named line of development within a project (similar to git). |
| Commit | An immutable snapshot of the model at a point in time. |
| Element | Any SysML element: parts, requirements, actions, connections, … |
Two tools that share nothing but this vocabulary can still talk about “the same model at the same version”. A commit is immutable, so any query pinned to a project and a commit is reproducible: the same request returns the same answer next month, regardless of what the model has become since. That is the property every downstream artifact – a coverage report, an exported diagram, an audit trail – should be built on.
On top of these concepts the specification defines resource-oriented services: listing and creating projects, walking a project’s branches and commits, retrieving and storing elements at a commit, navigating ownership and relationships, and a query language (PrimitiveConstraint / CompoundConstraint objects) for filtering elements server-side. The element payloads are JSON, governed by a published JSON Schema, so the shape of a PartUsage on the wire is as standardised as its textual syntax.
Where the OMG definition lives
The normative materials ship in the spec distribution:
references/sysmlv2/OpenAPI.json– the REST endpoints, request/response schemas, and error codes.references/sysmlv2/SysmlAPISchema.json– the element-payload JSON Schema.references/sysmlv2/Systems-Modeling-API.xmi– the underlying service architecture model.references/sysmlv2/SysML-v2-API-Cookbook/– Jupyter notebooks of common query patterns.
sysml-rs extends the spec here. sysml-rs implements the project/commit/model read side of the OMG API as a subset, and extends it with a native REST surface, WebSocket streams, and an MCP transport that share one in-process service – so a model loaded over REST is queryable from an MCP-aware assistant, and vice versa. The route tables, authentication and CORS defaults, session and streaming endpoints, and MCP setup are product documentation and live on the sysml-rs portal: Integrations. If your tooling needs strict OMG conformance for branch operations or the compound query objects, treat sysml-rs as a partial implementation and round-trip through a conformant store for those operations.
Working with a model API
These practices are about the interchange concepts, not any particular implementation; they hold against any conformant store.
Always pin a commit. Reports and exports should record the commit ID that produced them, so results are reproducible and auditable. Without a pinned commit, the same query can return different answers across runs – and nobody can tell whether the model changed or the report did.
Read first, write later. Build trust in your automation by producing useful reports before attempting programmatic model modifications. Read-only automation cannot corrupt model data; teams that jump straight to programmatic writes often create elements that conflict with manual modelling.
Query server-side. Downloading every element and filtering locally works for small models but does not scale. The query surface exists so the store does the filtering.
Keep automation narrow. One well-maintained coverage report is worth more than ten fragile scripts.
A good first target is requirement coverage: query for requirements lacking a verification case, and pair it with a requirement-to-verification traceability matrix (Chapter 10). It is read-only, it produces immediate review value, and it exercises the identity story end to end.
Further reading
- Chapter 15 – how the project/commit interchange notions relate to workspaces and manifests when you are authoring.
- Chapter 10 – the verification semantics behind coverage queries.
- The OMG materials listed above are the normative reference for endpoints, payloads, and the query language.