Simcraft Docs
Open the app

Validate a model#

This guide checks an OSDL document against the schemas and the component libraries it uses. Validation is mechanical JSON Schema checking; no engine is required.

Two phases#

Model validation always has two phases:

  1. The document is validated against the model schema. This checks structure, but treats every component's params object as opaque.
  2. Each component's params is validated against the parameter schema published in its type's library definition, with the core schema registered so shared value forms resolve.

A document can pass phase one and fail phase two. Phase two is what catches a misspelled parameter or a distribution where a scalar is required.

Run the repository validator#

The OSDL repository ships a validator that performs both phases over the specification's own schemas, libraries, and examples. From a checkout of github.com/simcrafthq/osdl, with Node.js 22:

sh
bash validate.sh

The command compiles all six schemas, checks each library document, and validates every example in both phases. When the Lean toolchain is available it also builds the reference machine and checks the conformance catalogue; set OSDL_REQUIRE_LEAN=1 to fail when Lean is missing, which is what continuous integration does.

Validate your own documents#

Any JSON Schema draft 2020-12 validator works for phase one. Point it at the published model schema and your document:

sh
npx ajv-cli validate --spec=draft2020 -s schemas/osdl.schema.json -d my-model.osdl.json

For phase two, validate each component's params against the matching params schema in the library definition, registering osdl.schema.json so $ref references to core value forms resolve.

Two rules save debugging time:

  • Identifiers match ^[A-Za-z_][A-Za-z0-9_-]*$, and component ids must be unique within their scope.
  • A parameter reference to an undeclared name, or a connection to a port that does not exist, is a load-time error even in a schema-valid document. Engines check references when they prepare the model.

Read more#