OSDL Model Document

Open Simulation Definition Language (OSDL) v0.1: a vendor-neutral, JSON-native format for discrete-event, agent-based, system-dynamics, and hybrid simulation models. This schema validates document structure (phase one). Component params objects are additionally validated against the params schema published in the component type's library definition (phase two). See SPEC.md for the semantics.

Generated from spec/schemas/osdl.schema.json · https://osdl.dev/schemas/0.1/osdl.schema.json

Document root#

Field	Type	Description
`$schema`	`string`	Optional URI of the OSDL JSON Schema, for editor tooling.
`osdl`required	`"0.1"`	Version of the OSDL specification this document conforms to.
`model`required	`model`
`experiments`	array<`experiment`>	Run configurations: duration, replications, seeds, parameter overrides, sweeps, and recorded outputs.
`views`	array<`view`>	Presentation-only layout (canvas positions, edge routing). Views must not affect simulation semantics.
`metadata`	`metadata`

Definitions#

`identifier`#

A name: starts with a letter or underscore, then letters, digits, underscores, or hyphens.

string pattern ^[A-Za-z_][A-Za-z0-9_-]*$

`typeName`#

A namespaced component type, <namespace>.<name>, e.g. des.queue. The namespace identifies the component library that defines the type. core.composite is reserved for a future additive version.

string pattern ^[a-z][a-z0-9_]*\.[a-z][a-zA-Z0-9_]*$

`portRef`#

A connection endpoint, <componentId>.<portId>, referring to a sibling component in the same model scope.

string pattern ^[A-Za-z_][A-Za-z0-9_-]*\.[A-Za-z_][A-Za-z0-9_-]*$

`statePath`#

A dotted path to an observable state variable, e.g. teller.utilization or patients.inState.sick.

string pattern ^[A-Za-z_][A-Za-z0-9_-]*(\.[A-Za-z_][A-Za-z0-9_-]*)+$

`eventType`#

A dotted event type name, e.g. entity.moved.

string pattern ^[a-z][a-zA-Z0-9]*(\.[a-z][a-zA-Z0-9]*)+$

`expressionString`#

An expression in the OSDL expression language (SPEC.md §7.3). References resolve to parameters, component state paths, and (in agent scope) agent attributes.

string min length 1

`metadata`#

Free-form extension data. Keys should be namespaced, for example com.example.tool. Metadata must not affect simulation semantics.

No properties.

`model`#

Field	Type	Description
`name`required	`identifier`
`label`	`string`	Human-readable display name.
`description`	`string`
`time`	`timeConfig`
`parameters`	array<`parameterDef`>	Model-level inputs, overridable per experiment and referenceable from any value position.
`components`required	array<`component`>
`connections`	array<`connection`>
`metadata`	`metadata`

`timeConfig`#

Field	Type	Description
`unit`	`"ticks"` \| `"milliseconds"` \| `"seconds"` \| `"minutes"` \| `"hours"` \| `"days"` \| `"weeks"` \| `"years"`	The unit of simulation time. All durations, delays, and rates in the model are expressed in this unit. default `"ticks"`
`start`	`number` \| `string`
`integration`	`integrationConfig`

`integrationConfig`#

Numerical integration settings for continuous components. The step size defines observable integration boundaries on the shared simulation clock. An implementation can use any internal integration design that preserves boundary behavior.

Field	Type	Description
`method`	`"euler"` \| `"rk4"`	default `"euler"`
`dt`	`number`	Integration step size, in model time units. default `1` · > 0

`parameterDef`#

Field	Type	Description
`name`required	`identifier`
`label`	`string`
`description`	`string`
`type`	`"number"` \| `"integer"` \| `"boolean"` \| `"string"`	default `"number"`
`default`	`number` \| `boolean` \| `string`
`unit`	`string`	Unit of measure, e.g. `patients/hour`. Informational in v0.1.
`min`	`number`
`max`	`number`
`choices`	array<`number` \| `string`>	If present, the parameter value must be one of these. min items 1
`metadata`	`metadata`

`component`#

Field	Type	Description
`id`required	`identifier`	Unique within the enclosing model scope.
`type`required	`typeName`
`label`	`string`
`description`	`string`
`params`	`object`	Configuration for this component instance. Validated (phase two) against the params schema in the component type's library definition.
`tags`	array<`string`>
`metadata`	`metadata`

`connection`#

Field	Type	Description
`id`	`identifier`	Optional, but required if the connection is referenced from a view route.
`from`required	`portRef`
`to`required	`portRef`
`label`	`string`
`params`	`object`	Library-defined link configuration (e.g. routing weight). Interpreted by the component types at the endpoints.
`tags`	array<`string`>
`metadata`	`metadata`

`paramRef`#

Field	Type	Description
`param`required	`identifier`	The name of a model parameter.

`expression`#

Field	Type	Description
`expr`required	`expressionString`

`scalarValue`#

A deterministic numeric value: a literal, a parameter reference, or an expression.

One of:

number

paramRef

expression

`numericValue`#

A possibly stochastic numeric value: a literal, a parameter reference, an expression, or a probability distribution (re-sampled at each use).

One of:

number

paramRef

expression

distribution

`value`#

A general value: literal, parameter reference, expression, or distribution. Plain strings are literals. Expressions must use the {"expr": ...} form.

One of:

number

boolean

string

paramRef

expression

distribution

`distribution`#

A probability distribution. Numeric arguments may themselves be parameter references or expressions.

One of:

dist: "constant"

Field	Type	Description
`dist`required	`"constant"`
`value`required	`scalarValue`

dist: "uniform"

Field	Type	Description
`dist`required	`"uniform"`
`min`required	`scalarValue`
`max`required	`scalarValue`

dist: "exponential"

Field	Type	Description
`dist`required	`"exponential"`
`rate`required	`scalarValue`	Events per model time unit; mean = 1/rate.

dist: "normal"

Field	Type	Description
`dist`required	`"normal"`
`mean`required	`scalarValue`
`std`required	`scalarValue`

dist: "lognormal"

Field	Type	Description
`dist`required	`"lognormal"`
`mu`required	`scalarValue`	Mean of the underlying normal (log space).
`sigma`required	`scalarValue`	Std of the underlying normal (log space).

dist: "triangular"

Field	Type	Description
`dist`required	`"triangular"`
`min`required	`scalarValue`
`mode`required	`scalarValue`
`max`required	`scalarValue`

dist: "weibull"

Field	Type	Description
`dist`required	`"weibull"`
`shape`required	`scalarValue`
`scale`required	`scalarValue`

dist: "gamma"

Field	Type	Description
`dist`required	`"gamma"`
`shape`required	`scalarValue`
`scale`required	`scalarValue`

dist: "beta"

Field	Type	Description
`dist`required	`"beta"`
`alpha`required	`scalarValue`
`beta`required	`scalarValue`

dist: "poisson"

Field	Type	Description
`dist`required	`"poisson"`
`rate`required	`scalarValue`	Mean count per draw.

dist: "binomial"

Field	Type	Description
`dist`required	`"binomial"`
`n`required	`scalarValue`	Number of trials (integer).
`p`required	`scalarValue`

dist: "bernoulli"

Field	Type	Description
`dist`required	`"bernoulli"`
`p`required	`scalarValue`

dist: "geometric"

Field	Type	Description
`dist`required	`"geometric"`
`p`required	`scalarValue`

dist: "discrete"

Field	Type	Description
`dist`required	`"discrete"`
`values`required	array<`object`>	Categorical distribution: each entry is drawn with probability weight/sum(weights). min items 1

dist: "empirical"

Field	Type	Description
`dist`required	`"empirical"`
`samples`required	array<`number`>	Observed data; draws resample from these values. min items 1

`statechart`#

A finite-state behaviour definition. Used by agent definitions and stateful components across paradigms.

Field	Type	Description
`initial`required	`identifier`	The id of the initial state.
`states`required	array<`state`>	min items 1
`transitions`	array<`transition`>

`state`#

Field	Type	Description
`id`required	`identifier`
`label`	`string`
`description`	`string`
`onEnter`	array<`action`>
`onExit`	array<`action`>

`transition`#

Field	Type	Description
`from`required	`identifier`
`to`required	`identifier`
`trigger`required	`trigger`
`guard`	`expressionString`	Boolean expression; the transition fires only if it evaluates true.
`actions`	array<`action`>
`label`	`string`

`trigger`#

One of:

type: "timeout"

Field	Type	Description
`type`required	`"timeout"`
`delay`required	`numericValue`	Fires after this much time in the source state.

type: "rate"

Field	Type	Description
`type`required	`"rate"`
`rate`required	`numericValue`	Exponential hazard: fires after Exp(rate)-distributed time; mean = 1/rate.

type: "condition"

Field	Type	Description
`type`required	`"condition"`
`expr`required	`expressionString`	Fires when the expression becomes true.

type: "message"

Field	Type	Description
`type`required	`"message"`
`topic`required	`string`	Fires when a message with this topic is received.

type: "arrive"

Field	Type	Description
`type`required	`"arrive"`
`port`required	`identifier`	Fires when this agent, having previously departed, arrives back at the named port of its population.

`action`#

One of:

type: "set"

Field	Type	Description
`type`required	`"set"`
`target`required	`string`	An agent attribute name (in agent scope) or a writable component state path. pattern `^[A-Za-z_][A-Za-z0-9_-](\.[A-Za-z_][A-Za-z0-9_-])*$`
`value`required	`value`

type: "send"

Field	Type	Description
`type`required	`"send"`
`topic`required	`string`
`to`	`"self"` \| `"connected"` \| `"random"` \| `"all"`	Recipients within the population: the agent itself, its network neighbours, one uniformly random agent, or every agent. default `"connected"`
`payload`	`object`

type: "emit"

Field	Type	Description
`type`required	`"emit"`
`event`required	`eventType`	Emits a custom event onto the simulation event stream.
`payload`	`object`

type: "depart"

Field	Type	Description
`type`required	`"depart"`
`port`required	`identifier`	The agent leaves its population as an entity through this out port (e.g. into a discrete-event process).

type: "log"

Field	Type	Description
`type`required	`"log"`
`message`required	`string`

`experiment`#

Field	Type	Description
`name`required	`identifier`
`label`	`string`
`description`	`string`
`duration`required	`number`	Run length in model time units. > 0
`warmup`	`number`	Initial period excluded from recorded outputs. min 0
`replications`	`integer`	default `1` · min 1
`seed`	`integer`	Root random seed. Replication r uses a stream deterministically derived from (seed, r). Engines must produce identical results for identical (model, experiment, seed, replication). min 0
`parameters`	map<string, `number` \| `boolean` \| `string`>	Fixed overrides of model parameter defaults, keyed by parameter name.
`sweep`	array<`object`>	Parameter sweep. The experiment runs once per element of the cross product of all entries' value lists (times `replications`). min items 1
`outputs`	array<`output`>
`stopWhen`	`expressionString`	Optional early-stop condition; the run ends when it evaluates true.
`metadata`	`metadata`

`output`#

A recorded observable with one or more independent recorders. The recorder type must support the observable's state type.

Field	Type	Description
`path`required	`statePath`
`as`	`identifier`	Alias used in results and `metric.updated` events.
`records`required	array<`recorder`>	min items 1

`recorder`#

One of:

type: "timeseries"

Records number or integer values at an interval or on change.

Field	Type	Description
`type`required	`"timeseries"`
`interval`	`number`	Sampling interval. If omitted, the value is recorded on every change. > 0

type: "summary"

Computes numeric statistics for a number or integer observable.

Field	Type	Description
`type`required	`"summary"`
`statistics`	array<`"mean"` \| `"std"` \| `"min"` \| `"max"` \| `"median"` \| `"p5"` \| `"p25"` \| `"p75"` \| `"p90"` \| `"p95"` \| `"p99"` \| `"count"` \| `"sum"` \| `"last"`>	Summary statistics to compute. The default is ["mean"]. min items 1

type: "final"

Records the final number, integer, boolean, or string value.

Field	Type	Description
`type`required	`"final"`

`view`#

Field	Type	Description
`id`required	`identifier`
`label`	`string`
`type`	`"canvas"`	default `"canvas"`
`elements`	array<`object`>
`routes`	array<`object`>
`metadata`	`metadata`

`point`#

Field	Type	Description
`x`required	`number`
`y`required	`number`

OSDL Model Document

Document root#

Definitions#

identifier#

typeName#

portRef#

statePath#

eventType#

expressionString#

metadata#

model#

timeConfig#

integrationConfig#

parameterDef#

component#

connection#

paramRef#

expression#

scalarValue#

numericValue#

value#

distribution#

statechart#

state#

transition#

trigger#

action#

experiment#

output#

recorder#

view#

point#

`identifier`#

`typeName`#

`portRef`#

`statePath`#

`eventType`#

`expressionString`#

`metadata`#

`model`#

`timeConfig`#

`integrationConfig`#

`parameterDef`#

`component`#

`connection`#

`paramRef`#

`expression`#

`scalarValue`#

`numericValue`#

`value`#

`distribution`#

`statechart`#

`state`#

`transition`#

`trigger`#

`action`#

`experiment`#

`output`#

`recorder`#

`view`#

`point`#