sysml-validate

Headless SysML v2 / KerML validation. Runs the same parser, linker, and diagnostics as the SysML v2 VS Code extension — the Problems panel, in a terminal or a CI job. No VS Code, no browser, no display server.

npx sysml-validate models/

models/control.sysml
  2:5    error  SYN067  Import visibility is required by the Release syntax; use 'private import' unless re-export is intended.

models/vehicle.sysml
  12:23  error  RES001  Could not resolve reference to Element named 'Engien'.

✖ 2 problems (2 errors) in 2 of 2 files

…and when the model is healthy:

✓ 2 files checked, no problems found

Colour is used on a terminal and dropped everywhere else — a pipe, a log file, or a coding agent's chat window gets exactly the plain text above. --color and --no-color force it either way, and NO_COLOR is honoured.

Usage

sysml-validate [paths...] [options]

  --format <fmt>        text | compact | json | sarif | github (default: text).
                        text     grouped and aligned, colour on a terminal
                        compact  file:line:col: severity [CODE]: message
  --out <path>          Write the report to a file instead of stdout.
  --strict              Fail on warnings as well as errors.
  --max-warnings <n>    Fail when more than n warnings are reported.
  --all                 Report informational notices and hints too.
  --lint-profile <p>    Override sysml.lint.profile: default | quiet | strict.
  --workspace <path>    Index this project for cross-file reference resolution.
  --no-config           Ignore .vscode/settings.json and .vscode/sysml/project.json.
  --library <path>      Standard-library directory (default: the bundled library).
  --color, --no-color   Force ANSI colour on or off (default: on a terminal only).

Paths may be files or directories; directories are searched recursively for .sysml and .kerml, skipping node_modules, VCS directories, build output, and vendored library trees. With no path, the working directory is checked. By default, no model file outside the paths you name is discovered or indexed. Use --workspace <path> only when references should resolve against other project files.

The OMG standard library ships with the package, so Real, ISQ::*, SI::* and the rest resolve with nothing else installed.

Examples

Check one file while you work. Paths, positions, severity, and the diagnostic code — everything needed to jump to the problem:

$ sysml-validate models/vehicle.sysml
models/vehicle.sysml
  12:23  error  RES001  Could not resolve reference to Element named 'Engien'.

✖ 1 problem (1 error) in 1 of 1 file

See the advisory notices too. Hints and info are out of the way by default — --all brings them in:

$ sysml-validate models/ --all
models/vehicle.sysml
  5:19   hint  RES016  'power' shadows a standard-library element of the same name; the library symbol is hidden in this scope.
  16:21  hint  SEM006  Requirement definition 'MassLimit' has no 'subject' declaration.

▲ 2 problems (2 hints) in 1 of 2 files

One line per problem for grep, an editor error matcher, or a coding agent that wants to parse the output:

$ sysml-validate models/ --format compact
models/control.sysml:2:5: error [SYN067]: Import visibility is required by the Release syntax; use 'private import' unless re-export is intended.
models/vehicle.sysml:12:23: error [RES001]: Could not resolve reference to Element named 'Engien'.

Compact prints nothing at all on a clean run, so [ -s report.txt ] and if sysml-validate . --format compact | grep . both behave.

Structured output for a script or a dashboard:

$ sysml-validate models/ --format json | jq '.counts, .diagnostics[0].code'
{
  "error": 2,
  "warning": 0,
  "info": 0,
  "hint": 0
}
"SYN067"

Gate a commit hook on errors, and allow a small warning budget:

$ sysml-validate models/ --max-warnings 5 && echo "model is publishable"

Check just what changed, without loading any model outside that list:

$ git diff --name-only --diff-filter=d origin/main | grep -E '\.(sysml|kerml)$' | xargs -r sysml-validate

If those files need definitions elsewhere in the checkout, opt into workspace indexing explicitly:

$ git diff --name-only --diff-filter=d origin/main | grep -E '\.(sysml|kerml)$' | xargs -r sysml-validate --workspace .

--workspace . indexes the rest of the project for reference resolution, but still reports diagnostics only for the files you named.

Use it from a coding agent. The default output is plain text with a stable one-line summary, so an agent can act on it directly:

$ sysml-validate models/ --format compact ; echo "exit=$?"
models/vehicle.sysml:12:23: error [RES001]: Could not resolve reference to Element named 'Engien'.
exit=1

Your project's configuration is honoured

The validator reads the settings your team commits, in the editor's own precedence — .vscode/settings.json first, then .vscode/sysml/project.json:

| Setting | Effect | |---|---| | sysml.lint.profile | default / quiet / strict style-notice volume | | sysml.validation.severities | Per-code severity overrides (e.g. { "SEM006": "warning" }) | | sysml.diagnostics.unusedImports | off / warning / error | | sysml.diagnostics.units | UNIT001–UNIT005 dimensional analysis on/off |

--lint-profile overrides the profile for one run, and --no-config ignores both files. Note that sysml.validation.severities covers the validator's own codes; unresolved-reference errors (RES001) come from the linker and are always errors.

Exit codes

| Code | Meaning | |---|---| | 0 | no blocking diagnostics | | 1 | errors, or warnings under --strict / --max-warnings | | 2 | the command line or the environment was wrong (bad flag, unreadable path) |

Informational notices and hints never fail a run; they are only printed with --all.

GitHub Actions

Fail the build on model errors, with inline annotations on the diff:

- uses: actions/setup-node@v4
  with: { node-version: 20 }

- name: Validate the SysML model
  run: npx sysml-validate models/ --format github --strict

Or upload SARIF so diagnostics land in Security → Code scanning and on the pull request:

- name: Validate the SysML model
  run: npx sysml-validate models/ --format sarif --out sysml.sarif
  continue-on-error: true

- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: sysml.sarif

License

The CLI uses the extension's Freeware License (see LICENSE). The vendored OMG standard library under resources/sysml.library keeps its upstream OMG LICENSE / LICENSE-GPL terms; see that directory's NOTICE.md.