Why a document format#

OSDL, the Open Simulation Definition Language, is a vendor-neutral JSON format for simulation models. An OSDL document is a complete, executable description of a model, its experiments, and its presentation. This page explains what that buys.

The document is the asset#

Most simulation models live inside the tool that made them, as project files in proprietary formats. The model cannot be read without a license or reproduced without the same version of the same software.

An OSDL model is a plain JSON file. It can be read in any editor, diffed and reviewed like code, and stored in version control next to the decisions it informed. Engines, editors, and libraries are built around the format, and each is replaceable. The format is the durable asset.

Three roles, one contract#

The specification defines conformance for three roles, so tools can participate without implementing everything:

Role	Obligation
Producer	Emits documents valid against the model schema. An editor, an SDK, a script, a language model.
Consumer	Accepts any valid document; ignores `metadata` and `views` it does not understand. A renderer, a linter, a documentation tool.
Engine	Implements the core execution semantics; refuses documents that use component libraries it does not support.

This site is itself a consumer: the schema pages, library pages, and example pages are generated from the documents they describe.

Semantics live in libraries#

The core specification defines the kernel: time, values, expressions, connections, entity transfer, experiments, events. Component behavior lives in library definitions with their own namespaces, versions, and conformance suites.

A library definition declares each component type's ports, parameter schema, observable state, emitted events, and a prose semantic contract. From the definition alone, with no engine present, a tool can render palettes, generate parameter forms, validate documents, and prompt a language model with precise component semantics. That is what makes the format machine-authorable, not just machine-readable.

Anyone can implement it#

The specification is written to be implemented independently. An engine implements the core execution semantics, declares which component libraries it supports, and substantiates the claim by running the public conformance suites. A component library is a published definition document in its own namespace, with its own version and its own conformance cases; publishing one requires no engine of your own.

The guarantee runs in both directions. A valid document that uses only the des namespace runs on any conformant engine that claims des, with the same recorded results and portable events. And a library you publish is usable from any tool that reads library definitions.

This is also what makes agent authorship dependable. Point a language model at the specification and the library definitions, let it write a model, and validate the result mechanically: first against the model schema, then each component's params against its library's parameter schema. Validation needs no engine, and a document that passes runs on any conformant engine that supports its libraries. Validate a model covers the checking; run the conformance suite covers what an implementation must prove.

Layout never changes results#

A document separates model from views. Views carry canvas positions and edge routes; engines must ignore them. A layout change touches views, a behavior change touches model, and a reviewer can tell them apart in a diff.

The same discipline applies to metadata, the extension escape hatch: it must not affect simulation semantics. Anything that does belongs in the schema, a library definition, or a spec proposal.