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.4metadata:5 source: https://skillmd.com/skills/ddunnock/sysmlkit6---78# Authoring SysML v2 with sysmlkit910Three rule systems govern whether model text is acceptable, and only one of them11is the language: the grammar, Cameo's front-end behaviour, and this program's12placement policy. `sysmlkit check` is the single findings stream over all three.1314## The loop15161. Edit the `.sysml` file.172. Run `sysmlkit check <file>` — or let the PostToolUse hook run it.183. Every finding names a rule id. For anything you do not recognise, run19 `sysmlkit explain <RULE-ID>` before changing anything.204. Fix, re-run, continue.2122Do not guess at a rule from its id, and do not work around a finding by moving23the element somewhere the check does not look. `explain` prints the evidence,24the fix, and the observation that would retire the rule.2526## What the ids mean2728- `ORG-*` — placement. These come from the program's profile29 (`sysml-standards.toml`) and vary per program. The profile is the authority,30 not your memory of another model.31- `M-*` — Cameo behaviour. These ship with the tool and are the same on every32 program running the same Cameo build.33- `SPEC42-*` — language conformance, from the validator. Fix the text it names.34- `SYSKIT-*` — the tool reporting on itself: a file that did not parse, a check35 that examined nothing, an expired waiver, a generated block edited by hand.3637## Grades, and what they entitle you to3839Every rule carries an evidence grade: `V` verified, `O` observed, `R` reasoned,40`C` correlated, `U` unverified. `C` and `U` rules **cannot** gate and appear in41the context file under "unsettled — do not rely on". Treat those as open42questions, not instructions, and do not turn one into a rule by acting on it.4344## Before writing new content4546- Placement first: work the ladder in the profile's namespace list, and stop at47 the first match. If the element could be reused unchanged by another program48 it is vocabulary; if it names a count, a location or a specific sibling it is49 instance content.50- Imports go where the profile says (`structure.import_location`), scoped to a51 package rather than a namespace root, and only along a row of the import52 matrix.53- Never put a hyphen or a leading digit in a declared name. It goes in the short54 name: `requirement <'SYS-INT-0142'> TrackLatency`.55- Use `doc` comments, never `//`. Cameo strips line comments on save.5657## When a view renders empty5859Three shapes produce an empty table and none of them is an error: an `expose` at60a dead path, a filter on a marker nothing carries, and an attribute-reading61filter whose attribute type is not imported `public`. Run62`sysmlkit explain M-13` and `sysmlkit explain M-23` before assuming content is63missing.