Authoring SysML v2 with sysmlkit
Three rule systems govern whether model text is acceptable, and only one of them
is the language: the grammar, Cameo's front-end behaviour, and this program's
placement policy. sysmlkit check is the single findings stream over all three.
The loop
- Edit the
.sysml file.
- Run
sysmlkit check <file> — or let the PostToolUse hook run it.
- Every finding names a rule id. For anything you do not recognise, run
sysmlkit explain <RULE-ID> before changing anything.
- Fix, re-run, continue.
Do not guess at a rule from its id, and do not work around a finding by moving
the element somewhere the check does not look. explain prints the evidence,
the fix, and the observation that would retire the rule.
What the ids mean
ORG-* — placement. These come from the program's profile
(sysml-standards.toml) and vary per program. The profile is the authority,
not your memory of another model.M-* — Cameo behaviour. These ship with the tool and are the same on every
program running the same Cameo build.SPEC42-* — language conformance, from the validator. Fix the text it names.SYSKIT-* — the tool reporting on itself: a file that did not parse, a check
that examined nothing, an expired waiver, a generated block edited by hand.
Grades, and what they entitle you to
Every rule carries an evidence grade: V verified, O observed, R reasoned,
C correlated, U unverified. C and U rules cannot gate and appear in
the context file under "unsettled — do not rely on". Treat those as open
questions, not instructions, and do not turn one into a rule by acting on it.
Before writing new content
- Placement first: work the ladder in the profile's namespace list, and stop at
the first match. If the element could be reused unchanged by another program
it is vocabulary; if it names a count, a location or a specific sibling it is
instance content.
- Imports go where the profile says (
structure.import_location), scoped to a
package rather than a namespace root, and only along a row of the import
matrix.
- Never put a hyphen or a leading digit in a declared name. It goes in the short
name:
requirement <'SYS-INT-0142'> TrackLatency.
- Use
doc comments, never //. Cameo strips line comments on save.
When a view renders empty
Three shapes produce an empty table and none of them is an error: an expose at
a dead path, a filter on a marker nothing carries, and an attribute-reading
filter whose attribute type is not imported public. Run
sysmlkit explain M-13 and sysmlkit explain M-23 before assuming content is
missing.
1---2name: sysmlkit3description: Author and edit SysML v2 model text that conforms to the program's placement standard and to Cameo's front-end behaviour. Use whenever writing, editing or reviewing a .sysml file, choosing which namespace or package an element belongs in, writing imports between namespaces, naming packages or elements, or interpreting a sysmlkit finding or rule id such as ORG-ROOT-CONTENT or M-51. Also use when asked where something goes in the model, why a Cameo view renders empty, or whether an import is allowed.4---56# Authoring SysML v2 with sysmlkit78Three rule systems govern whether model text is acceptable, and only one of them9is the language: the grammar, Cameo's front-end behaviour, and this program's10placement policy. `sysmlkit check` is the single findings stream over all three.1112## The loop13141. Edit the `.sysml` file.152. Run `sysmlkit check <file>` — or let the PostToolUse hook run it.163. Every finding names a rule id. For anything you do not recognise, run17 `sysmlkit explain <RULE-ID>` before changing anything.184. Fix, re-run, continue.1920Do not guess at a rule from its id, and do not work around a finding by moving21the element somewhere the check does not look. `explain` prints the evidence,22the fix, and the observation that would retire the rule.2324## What the ids mean2526- `ORG-*` — placement. These come from the program's profile27 (`sysml-standards.toml`) and vary per program. The profile is the authority,28 not your memory of another model.29- `M-*` — Cameo behaviour. These ship with the tool and are the same on every30 program running the same Cameo build.31- `SPEC42-*` — language conformance, from the validator. Fix the text it names.32- `SYSKIT-*` — the tool reporting on itself: a file that did not parse, a check33 that examined nothing, an expired waiver, a generated block edited by hand.3435## Grades, and what they entitle you to3637Every rule carries an evidence grade: `V` verified, `O` observed, `R` reasoned,38`C` correlated, `U` unverified. `C` and `U` rules **cannot** gate and appear in39the context file under "unsettled — do not rely on". Treat those as open40questions, not instructions, and do not turn one into a rule by acting on it.4142## Before writing new content4344- Placement first: work the ladder in the profile's namespace list, and stop at45 the first match. If the element could be reused unchanged by another program46 it is vocabulary; if it names a count, a location or a specific sibling it is47 instance content.48- Imports go where the profile says (`structure.import_location`), scoped to a49 package rather than a namespace root, and only along a row of the import50 matrix.51- Never put a hyphen or a leading digit in a declared name. It goes in the short52 name: `requirement <'SYS-INT-0142'> TrackLatency`.53- Use `doc` comments, never `//`. Cameo strips line comments on save.5455## When a view renders empty5657Three shapes produce an empty table and none of them is an error: an `expose` at58a dead path, a filter on a marker nothing carries, and an attribute-reading59filter whose attribute type is not imported `public`. Run60`sysmlkit explain M-13` and `sysmlkit explain M-23` before assuming content is61missing.
ddunnock