person Tia Zanella
calendar_add_on Created March 5, 2026
update Updated March 21, 2026
Share
download Download MD

OSIRIS JSON Validate

OSIRIS validation is designed to be local-first, deterministic, and usable in both interactive workflows and CI pipelines.

The canonical validation path is the OSIRIS CLI package:

  • Package name: @osirisjson/cli
  • Canonical engine behind the CLI: @osirisjson/core
  • Primary command: validate

What the validator checks

OSIRIS validation is intentionally layered:

  1. Level 1: Structural Validates JSON Schema conformance: required fields, field types, enums, formats, and top-level shape.

  2. Level 2: Semantic Validates internal graph consistency: duplicate IDs, broken references, invalid group hierarchies, and similar integrity issues.

  3. Level 3: Domain Runs optional best-practice checks that improve interoperability and quality without redefining what counts as valid OSIRIS JSON document.

Validation profiles

The CLI is designed around three profiles:

  • basic Runs Level 1 only. Use it for quick structural checks.

  • default Runs Level 1 + Level 2. This is the expected day-to-day validation profile.

  • strict Runs Level 1 + Level 2 + selected Level 3 rules. This is the recommended profile for CI and release gates.

NPM installation

Run without global installation

npx @osirisjson/cli validate ./example.json

This is the recommended way to run the validator in CI or when you do not want a global install.

Install globally

npm install -g @osirisjson/cli
osirisjson validate ./example.json

Add as a project dependency

npm install --save-dev @osirisjson/cli
npx @osirisjson/cli validate ./example.json

Validation commands

Validate one file

npx @osirisjson/cli validate osiris-document-example.json

Validate multiple files

npx @osirisjson/cli validate osiris-document-example-01.json osiris-document-example-02.json

Validate a directory

Expands to all .json files in the directory (non-recursive):

npx @osirisjson/cli validate ./exports/

Validate from standard input

cat osiris-document-example.json | npx @osirisjson/cli validate -

Validate with the strict profile

npx @osirisjson/cli validate --profile strict ./exports/

Emit machine-readable JSON

npx @osirisjson/cli validate --profile strict --format json ./exports/

Override schema resolution

Use a local schema file instead of the bundled one:

npx @osirisjson/cli validate --schema ./osiris.schema.json topology.json

Verbose output

Show detailed diagnostics including source snippets (text format only):

npx @osirisjson/cli validate --verbose topology.json

Control color output

npx @osirisjson/cli validate --color never ./exports/

Expected exit codes

The CLI contract defines stable exit codes:

  • 0 = success Validation ran and no error diagnostics were emitted.

  • 1 = validation error Validation ran and at least one error diagnostic was emitted.

  • 2 = operational error Validation could not run for one or more inputs because of unreadable files, invalid JSON, bad flags, or similar pre-validation failures.

Output modes

The CLI is designed to support two output formats:

Human-readable text

Default terminal output for local usage:

  • file path
  • line/column when available
  • severity
  • diagnostic code
  • human-readable message

Machine-readable JSON

Use --format json for CI, scripts, dashboards, or downstream tooling.

For a single input, the CLI emits one pretty-printed JSON object to stdout. For multiple inputs, it emits NDJSON (one compact JSON object per line).

Local-first and offline-first by design

OSIRIS JSON validation is intended to run locally by default.

  • The CLI MUST NOT fetch data from the network during validation.
  • $schema is treated as a version hint, not as a live URL to fetch.
  • Bundled or cached schemas are used for resolution.

This matters because infrastructure topology documents MAY contain sensitive design information, even when secrets have already been removed.

Producers

Validate before publishing any document:

npx @osirisjson/cli validate --profile strict output.json

Consumers and CI pipelines

Validate on receipt before processing or storing the document.

Editors and integrations

Use the same engine behavior as the CLI by delegating validation to @osirisjson/core.

Follow progress

arrow_back Previous Cisco Next Preface arrow_forward
edit_note

Help improve this page

Found an issue or want to contribute? Open an issue.

bug_report Report Issue