OSDL: Open Simulation Definition Language#
Version 0.1 (draft)
OSDL is a vendor-neutral, JSON-native format for describing simulation models across paradigms: discrete-event (DES), agent-based (ABM), system dynamics (SD), and hybrids of all three. An OSDL document is a complete, executable description of a model, its experiments, and its presentation. Visual editors, code SDKs, language models, and engines can read and write the document.
The OSDL artifacts divide the public contract by concern. This document defines OSDL Core. The JSON Schemas define exchange structures. Component library specifications define optional component behavior. Implementation contracts can add implementation-specific rules:
schemas/osdl.schema.json: model documentsschemas/osdl.library.schema.json: component library definitionsschemas/osdl.events.schema.json: the simulation event streamschemas/osdl.results.schema.json: recorded resultslibraries/: optional component librariescontracts/reference-machine/CONTRACT.md: the optional component runtime and run-control implementation contractmachine/: the executable Lean reference machinemachine/README.md: reference machine scope and use
The schemas define document, event, and result structure. This document defines current core behavior. A library specification defines behavior for its namespace and version. An implementation contract applies only when a runner selects it.
1. Conformance#
The words must, must not, should, and may carry their RFC 2119 requirement force.
Every engine implements OSDL Core. Three conformance roles exist:
- A producer (editor, SDK, generator) emits OSDL documents. Producers must emit documents valid against the model schema.
- A consumer (renderer, linter, documentation tool) reads OSDL documents. Consumers must accept any valid document, and must ignore
metadatacontent andviewsthey do not understand. - An engine executes OSDL documents. Engines must implement the core execution semantics. An engine must implement a component library only when it declares support for that library namespace and version. It must refuse a document that uses an unsupported component type.
Implementations compare recorded results and portable events on conformance cases. They may use different calendars, storage, callbacks, and telemetry. Those design choices are conformant when valid documents, recorded results, and portable events remain compatible.
A conformance module can extend another module. A child module may add cases and assertions or make a comparison stricter. It must not reinterpret a parent field, change a parent recorded result, replace a parent case, or weaken a parent requirement. A runner resolves the extension graph, rejects cycles, and runs parent suites before child suites.
An implementation contract adds rules for an implementation class. A runner, build configuration, or test harness selects the contract outside an OSDL document. An OSDL document does not select an implementation contract.
2. Document structure#
A model document is a single JSON object:
| Field | Required | Purpose |
|---|---|---|
osdl |
yes | Spec version. Exactly "0.1" for this version. |
model |
yes | The model: parameters, components, connections (section 3). |
experiments |
no | Run configurations (section 9). |
views |
no | Presentation-only layout (section 11). |
metadata |
no | Free-form extension data (section 13). |
Documents should use the extension .osdl.json.
3. Names and references#
- Identifiers (
id,name, parameter names, state ids, port ids) match^[A-Za-z_][A-Za-z0-9_-]*$. Component ids must be unique within their model scope; parameter names must be unique within their model. In OSDL 0.1 a document has one model scope, so every component id is unique in the document. - Type names are namespaced:
des.queue,abm.population. The namespace identifies the library that defines the type (section 12). The namespacescore,des,abm,sd, anddataare reserved. - Port references (
from/toin connections) take the formcomponentId.portIdand must refer to a sibling component in the same model scope. - State paths address observable state:
componentId.stateId(e.g.teller.utilization). Paths may have more segments where a library defines dynamic state (e.g.patients.inState.sick).
4. The model#
4.1 Time#
model.time.unit declares the unit of simulation time (default ticks). steps is an alias of ticks: the two values name the same unit. Every duration, delay, rate, and dt in the model is expressed in this unit. time.start may map t = 0 to a number or an ISO 8601 date-time; engines and tools may use it to display calendar time. time.integration configures continuous integration (section 8.4).
4.2 Parameters#
model.parameters declares the model's tunable inputs: name, type (number, integer, boolean, string), default, optional bounds, choices, and unit. Parameters are referenced from value positions with {"param": "name"} and from expressions by bare name. Experiments override defaults (section 9). A parameter reference to an undeclared name is an error at load time.
5. Components#
A component is an instance of a type defined in a library: {"id": ..., "type": ..., "params": {...}}. The library definition (section 12) determines what ports it exposes, what its params mean, what state it publishes, and what events it emits.
Validation has two phases:
- The document is validated against the model schema. This checks structure but treats every
paramsobject as opaque. - Each component's
paramsis validated against the params schema published in its type's library definition.
Both phases are mechanical JSON Schema validation; the second requires the relevant library definitions, with the core schema registered for $ref resolution.
6. Ports and connections#
A connection joins an out port to an in port: {"from": "a.out", "to": "b.in"}. Direction is data/entity flow.
- A port accepts at most one connection unless its library definition sets
multiple: true. - Multiple connections on a
multipleout port have library-defined fan-out semantics (e.g.des.routerselects exactly one per entity). Multiple connections on amultiplein port merge (fan-in). - A port whose library definition declares
connectsTojoins only the ports it lists, each named by component type and port id. A connection is valid only when each end that declaresconnectsTolists the other end. A port withoutconnectsToadds no restriction of its own. - Connections may carry
paramsinterpreted by the endpoint component types. - A connection
idis optional but required for the connection to be referenced from a view route.
6.1 Port kinds#
A library definition declares each port's kind: entity, message, or value. The default is entity. A connection must join two ports of the same kind, out to in. Engines must reject a document whose connections violate declared direction, kind, multiplicity, or connectsTo before execution, and must resolve every connection to a stable prepared route before a run starts. Routing behavior must not depend on undocumented array positions.
- Entity ports carry entities under the escrow transfer protocol of section 6.2.
- Message ports deliver immutable payloads at the current simulation time with no custody: delivery is fire-and-forget and emits
message.sent. - Value ports carry typed scalar values. Publishing a value output delivers the value to every connected input at the current simulation time and emits
value.changed; the receiving library's value-delivery contract defines how the component observes the change.
6.2 Entity transfer#
Entity transfer uses kernel escrow with an explicit acceptance decision. When a sender sends an entity through a prepared route, the engine assigns the transfer a persistent transfer identity, takes the exact entity into escrow, and delivers it to the receiving component at the current simulation time. The receiver returns one of two decisions:
accept: the entity moves atomically at the current simulation time and the engine emitsentity.moved. The sender observes adeliveredsend result for the transfer.block: the exact entity remains in engine escrow, custody remains with the sender, and the sender observes ablockedsend result carrying the transfer identity and no entity value. A full bounded queue is one reason to block.
One transfer identity persists through the pending and blocked states, and each transfer has exactly one current or terminal result: delivered, blocked, or cancelled. A sender may cancel its own transfer before acceptance; the transfer becomes cancelled and custody of the entity stays with the sender. A receiver cannot return, replace, or retain a blocked entity: the acceptance decision carries no entity value. Engines must not lose, duplicate, or substitute entities.
When a receiver later reports readiness for an input port, the engine redelivers blocked transfers destined to that port, oldest first. The exact readiness correlation, targeted retry operation, and multi-route retry order are provisional in this draft, pending an identity-based transfer prototype; the redelivery rule in the reference machine contract is the interim behavior.
7. Values#
Component params, trigger arguments, and action values use these value forms:
| Form | Example | Meaning |
|---|---|---|
| Literal | 0.9, "fifo", true |
A constant. Plain strings are always literals. |
| Parameter reference | {"param": "arrivalRate"} |
The current value of a model parameter. |
| Expression | {"expr": "1 / treatmentTime"} |
Evaluated in the OSDL expression language (section 7.3). |
| Distribution | {"dist": "exponential", "rate": 0.9} |
A random variate, re-sampled at each use (section 7.2). |
Schema positions narrow which forms are allowed: scalarValue excludes distributions; numericValue allows all numeric forms.
7.1 Sampling#
A distribution in a param is sampled once per use as defined by the component (e.g. des.source.interarrival per creation, des.server.serviceTime per entity). Distribution arguments may themselves be parameter references or expressions, evaluated at sample time.
7.2 Distributions#
constant(value), uniform(min, max), exponential(rate), normal(mean, std), lognormal(mu, sigma), triangular(min, mode, max), weibull(shape, scale), gamma(shape, scale), beta(alpha, beta), poisson(rate), binomial(n, p), bernoulli(p), geometric(p), discrete(values), empirical(samples). Rates are per model time unit. Parameter names and semantics are fixed by the model schema.
Sampler algorithms are part of this specification. Determinism pins both the random streams and the exact algorithm that turns uniform bits into variates. Section 8.1 defines the streams and each sampler, including its draw count. The algorithms are inverse-CDF for the closed-form univariates, Box-Muller (cosine branch) for the normal, and pinned compositions (Marsaglia-Tsang, gamma ratios, Knuth) for the rest. Fixed cases in machine/GenerateVectors.lean generate the committed per-distribution vectors in machine/vectors/golden.txt. Adopting these samplers replaced the previously unspecified library algorithms in a one-time seed break. The determinism promise of section 8.1 is per OSDL version until 1.0.
7.3 Expressions#
Expressions are strings in a small, total, side-effect-free language:
expr = or ;
or = and { "||" and } ;
and = comparison { "&&" comparison } ;
comparison = additive { ( "<" | "<=" | ">" | ">=" | "==" | "!=" ) additive } ;
additive = multiplicative { ( "+" | "-" ) multiplicative } ;
multiplicative = unary { ( "*" | "/" | "%" ) unary } ;
unary = [ "-" | "!" ] power ;
power = primary [ "^" unary ] ;
primary = number | "true" | "false" | reference | call | "(" expr ")" ;
reference = identifier { "." identifier } ;
call = identifier "(" [ expr { "," expr } ] ")" ;Built-in functions: abs, min, max, floor, ceil, round, sqrt, exp, ln, log10, pow(x, y), sin, cos, tan, if(cond, a, b), time() (current simulation time). Constants: pi, e. Chained comparisons compare adjacent operands, so a < b < c is equivalent to a < b && b < c.
Reference resolution uses this order: agent attributes in agent scope, model parameters from the inner scope outward, then component state paths (componentId.stateId). An unresolvable reference is an error at load time. Numbers are IEEE 754 doubles. Booleans coerce to 1 or 0 in numeric positions. Division by zero and domain-invalid or non-finite math results are run-time errors.
7.4 Numeric evaluation#
Every numeric value is an IEEE 754 binary64 double. Each arithmetic operation rounds its exact result once, to the nearest double with ties to even. An implementation must not fuse operations, as a fused multiply-add does, and must not reorder or regroup them. A formula in this specification runs in its written order: operators bind by the usual precedence, and operators of equal precedence apply from left to right. A library specification that adds arithmetic states its operation order. A decimal constant in a formula is the nearest double to that decimal. An integer operand, such as a count, converts to the nearest double before it enters a double operation. Section 8.1 defines the integer arithmetic of the random streams.
min(a, b) and max(a, b) return a when a and b compare equal. This defines the sign of a zero result: max(0, -0) is 0, and max(-0, 0) is -0. With more than two arguments, min and max return the first argument that compares equal to the result.
round(x) returns the nearest integer to x. A value halfway between two integers rounds away from zero, so round(2.5) is 3 and round(-2.5) is -3. A zero result has the sign of x, so round(-0.4) is -0.
a % b returns the remainder a - b × trunc(a / b), computed exactly. The exact remainder is always a double, so the operation does not round. The result has the sign of a: -7 % 3 is -1, 7 % -3 is 1, and -6 % 3 is -0. a % 0 is a run-time error.
a ^ b returns pow(a, b).
sqrt is correctly rounded. This version does not pin the rounding of exp, ln, log10, pow, sin, cos, and tan, so a result that depends on them can differ between implementations in the last bits. The golden vectors in machine/vectors/golden.txt record the reference machine's values for the samplers that use these functions. The expr lines in the same file record the exact results of round and % for the cases above.
8. Execution semantics#
OSDL Core defines observable semantics: event ordering, entity escrow and custody, port behavior, state publication, run completion, recorded results, and portable events. It does not require a particular class hierarchy, callback layout, calendar representation, or programming language. Components react to typed events and issue commands; the concrete authoring interface for the reference machine is the component runtime contract in contracts/reference-machine/CONTRACT.md, which an implementation adopts explicitly.
8.1 The kernel#
Execution uses one simulation clock per run. Scheduled work is ordered by (time, phase, insertion sequence). Each simulation time has three phases. In the first phase, the run executes the work that a model driver schedules to run first at a time. A model driver is a participant that a component library adds to a run to coordinate the components of its namespace, such as the integrator of the sd library (section 8.4). In the second phase, the run executes the other work that can change state. In the third phase, the run executes the recording work: the interval samples and the warmup boundary. Ties within one phase execute in scheduling order. A model driver that schedules the advance of its components to run first therefore runs before the other work at that time. A sample reports the state after every piece of work at its time has run. For example, when an arrival and a sample are both scheduled for time 1.0, the sample counts that arrival. There is one exception. When a stopWhen expression or a component request stops a run, only the recording work still due at the stop time runs (section 9). Recording writes no component state, so the recording phase changes the values a run records, not the state it computes. All paradigms share these observable scheduling semantics. There is no user-controlled event priority among the kinds of work that change state. An implementation may use a different internal calendar or scheduler when it preserves the defined results and portable events.
A run dispatches scheduled work up to the end time limit duration + duration × 10⁻¹². The margin duration × 10⁻¹² is the nearest double to 10⁻¹², multiplied by duration and rounded to a double. The limit is duration plus the margin, rounded to a double, with no fused multiply-add. Work within the limit runs at its scheduled time, also after duration. Work past the limit does not run. The margin admits a step time that rounds past a decimal duration: with duration 0.7, step 7 of a 0.1 grid is at 7 × 0.1, which is 0.7000000000000001, and runs at that time. Step 8 is past the limit and does not run. The margin grows with duration. At duration 10⁹, the margin is 10⁻³, so a timer 0.0005 after duration runs.
On endTime completion, the final time is the later of the clock and duration, and component finalization runs at that time. In the run above, the final time is 0.7000000000000001.
Timers have identity. A component schedules a timer at a relative delay or an absolute time and receives a timer identifier. A pending timer can be cancelled or rescheduled; a rescheduled timer receives a new insertion sequence. Engines must reject non-finite times, negative relative delays, absolute times in the past, and overflowed times. Cancelling a timer that is not pending is a no-op; rescheduling one is an error. The last two rules are provisional pending the timer negative-case prototype.
Observable component state is typed: a published state value is a number, integer, boolean, or string. Absence is an absent observation, never a published null. Numeric positions coerce integers by widening and booleans to 1/0; strings do not coerce, and a numeric expression that reads a string observation is a run-time error. State publication is distinct from event emission and from value-port delivery.
An engine separates immutable model preparation from run instances. Preparation resolves and validates topology, ports, routes, parameters, expressions, distributions, outputs, and state references; one prepared model supports many runs. Each run exposes structured run control: step executes exactly one calendar-dispatch semantic unit; run is equivalent to repeated step until a terminal status; inclusive runThrough processes every scheduled event at or before a target time and stops before the first event after it, and treats a target at or past duration as the end time limit; nextEventTime reports the next scheduled time within the end time limit. With duration 0.7 and the 0.1 grid above, nextEventTime reports 0.7000000000000001 for step 7, and runThrough to 0.7 runs step 7 and then completes the run. External input is admitted only through validated external ports at explicit simulation times, ordered by the same calendar mechanism as internal events; each admitted input becomes an immutable run-owned record with a deterministic admission ordinal, and input at a non-finite or past time is rejected without effect. A host may request cancellation; the request is observed between dispatch transactions.
Every terminal execution path produces one run report containing the run status, final time, recorded results, the complete available trace, and diagnostics. Run status is one of:
- Completed, with reason
endTime(the next event lies past the end time limit),condition(astopWhenexpression became nonzero),requested(a component requested completion), orquiescent(the calendar is empty). Component finalization runs only for normal completion and receives the reason. - Failed: a semantic model or component failure, carrying a structured diagnostic.
- Aborted, with reason
budgetExceededorcancelled. These are host or implementation-policy outcomes, not semantic failures; execution budgets are implementation policy and must not change portable outputs for valid runs.
Diagnostics are structured: a stable code, a message, and, when known, the component, the operation, the simulation time, and the document location. Tools must not need to parse human-readable messages.
A run is a pure function of (document, experiment, parameters, seed, admitted external inputs). Within an engine version, replay of that tuple is bit-exact. This draft makes the determinism promise per OSDL version.
Cross-implementation conformance compares recorded results and portable events. It does not require exact raw trace equality. Runtime budgets, capability validation, telemetry cadence, callback layout, and other implementation policy are not core semantics. An implementation contract can define those rules for implementations that select it.
Random streams and samplers#
Every random draw comes from a labeled stream. Each component has one stream, labeled with its component id. Each model driver has one stream, labeled with its driver id. Component ids are unique in a document (section 3), and a driver id starts with $, which a component id cannot contain, so every stream label is unique. A later version that adds nested model scopes must define a unique stream label, for example the component's id path. All streams of a run derive from the replication seed seed_r (section 9). A component takes draws from its own stream in the order it makes them, so adding a component does not change the draws of another component.
These definitions fix the streams. Integer arithmetic wraps: 64-bit values modulo 2⁶⁴, and the generator state modulo 2¹²⁸.
le64(x)is the 8 bytes of the unsigned 64-bit integerx, least significant byte first.utf8(s)is the UTF-8 bytes of the strings.fnv1a(p₁, …, pₙ)hashes a list of byte strings to a 64-bit value. It starts withh = 0xcbf29ce484222325. For each bytebof a part, it setsh = (h xor b) × 0x100000001b3. After each part, it setsh = (h xor 0xff) × 0x100000001b3. This separator step runs after every part, including the last. It keeps the parts("ab", "c")and("a", "bc")apart, and it makesfnv1adiffer from standard FNV-1a.- A stream with label
labelstarts in the 128-bit states = fnv1a(le64(seed_r), utf8(label)) | 1. The 64-bit hash fills the low 64 bits ofs, and the high 64 bits are zero. The bitwise or with1makessodd. - Each draw is one step of PCG64-MCG with the XSL-RR output function. The step first sets
s = s × 0x2360ed051fc65da44385df649fccf645modulo 2¹²⁸. It then returns the 64-bit valuerotr(hi(s) xor lo(s), s >> 122).hi(s)andlo(s)are the high and low 64 bits ofs.rotr(x, n)rotates the 64-bit valuexright bynbits, andnis in0to63. - The uniform variate of one draw
bitsisu = (bits >> 11) × 2⁻⁵³, a double in[0, 1).
The samplers turn uniform variates into the distributions of section 7.2. Each u below is one draw, and draws happen in the order written. Formulas follow the operation order of section 7.4. 2π is the double 6.283185307179586. A uniform index in 0 to k - 1 takes one draw and is min(floor(u × k), k - 1).
| Distribution | Draws | Value |
|---|---|---|
constant(value) |
0 | value. |
uniform(min, max) |
1 | min + (max - min) × u. |
exponential(rate) |
1 | -ln(1 - u) / rate. |
normal(mean, std) |
2 | mean + std × z, with z = sqrt(-2 × ln(1 - u₁)) × cos(2π × u₂). |
lognormal(mu, sigma) |
2 | exp(mu + sigma × z), with z as for normal. |
triangular(min, mode, max) |
1 | With f = (mode - min) / (max - min): min + sqrt((max - min) × (mode - min) × u) when u < f, and max - sqrt((max - min) × (max - mode) × (1 - u)) otherwise. |
weibull(shape, scale) |
1 | scale × pow(-ln(1 - u), 1 / shape). |
bernoulli(p) |
1 | 1 when u < p, and 0 otherwise. |
binomial(n, p) |
n |
The number of draws with u < p. |
geometric(p) |
1, or 0 when p = 1 |
floor(ln(1 - u) / ln(1 - p)), and 0 without a draw when p = 1. |
discrete(values) |
1 | Let t be the sum of the weights, added in order from 0, and let d = t × u. The sampler walks the values in order. It returns the first value whose weight is greater than d, and it subtracts each skipped weight from d. When no value is returned, the result is the last value. |
empirical(samples) |
1 | The sample at a uniform index in 0 to k - 1, where k is the number of samples. |
gamma(shape, scale) |
Varies | scale × G(shape) when shape ≥ 1. When shape < 1, scale × G(shape + 1) × pow(1 - u, 1 / shape), with u drawn after G. |
beta(alpha, beta) |
Varies | x / (x + y), where x is gamma(alpha, 1) and is drawn before y, which is gamma(beta, 1). |
poisson(rate) |
Varies | The sum, from 0, of K(λ) over parts of the rate. While the remaining rate is greater than 500, the sampler adds K(500) and subtracts 500 from the remaining rate. It then adds K of the remaining rate. The split keeps exp(-λ) from underflowing. |
G(a), for a ≥ 1, is the Marsaglia-Tsang method. Let d = a - 1 / 3 and c = 1 / (3 × sqrt(d)). Each iteration takes z as for normal, with two draws, and sets v = (1 + c × z) × (1 + c × z) × (1 + c × z). When v ≤ 0, the next iteration starts. Otherwise the iteration draws u. It returns d × v when u < 1 - 0.0331 × z × z × z × z. Only when that test fails, it also returns d × v when ln(u) < 0.5 × z × z + d × (1 - v + ln(v)). Otherwise the next iteration starts. Inside a sampler, ln(0) is negative infinity and is not a run-time error, so a draw of u = 0 passes the second test.
K(λ) is Knuth's method. It starts with L = exp(-λ), p = 1, and k = 0. Each iteration draws u and sets p = p × u. It returns k when p ≤ L, and otherwise adds 1 to k and starts the next iteration.
Each call of G or K that runs 10,000 iterations without returning a value is a run-time error.
8.2 Discrete events (DES)#
The optional des library defines discrete-event component behavior. DES components react to entity arrivals, timer events, and send results, mutate their state, and send entities per the core transfer rules in section 6. State changes are visible immediately to subsequent events.
8.3 Agents (ABM)#
The optional abm library defines agent-based component behavior. Agent transitions, messages, and entity transfers use the core clock, values, connections, and event envelopes. An engine has no ABM obligation unless it declares support for the abm namespace and version.
8.4 Continuous dynamics (SD)#
The optional sd library defines system dynamics component behavior. time.integration.dt defines observable integration boundaries on the shared simulation clock. The value is 1.0 model time units when dt is omitted. Boundary n, for n = 1, 2, and so on, is at time n × dt, computed as one IEEE 754 double product.
The step to an integration boundary runs before every other piece of work at that boundary's time. A discrete event at a boundary time therefore observes the stock values for that time, and the changes it makes feed the next step. Between boundaries, a discrete event observes the values of the last boundary. An implementation may use any internal integration design that preserves these boundary values, recorded results, and portable events. An engine has no SD obligation unless it declares support for the sd namespace and version.
9. Experiments#
An experiment names a run configuration: duration (required), warmup (excluded from outputs), replications, seed, fixed parameter overrides, an optional sweep, recorded outputs, and an optional stopWhen expression.
- A sweep runs the cross product of all entries' value lists; each point in the product runs
replicationstimes. - Scenarios are numbered from 0 through the cross product of the sweep entries. The last entry varies fastest, and each entry's values follow their array order. A run without a sweep has one scenario, scenario 0. Replications of a scenario are numbered from 1 to
replications. - Replication
rof scenarioshas the replication seedseed_r = fnv1a(le64(seed), le64(s), le64(r)) & (2⁵³ - 1).seed_rdepends on bothsandr.seedis the experiment's root seed, an integer from 0 to 2⁶⁴ - 1, and it is 0 when the experiment omits it. An engine readsseedexactly as an unsigned 64-bit integer, because a double cannot hold every such value.fnv1aandle64are defined in section 8.1. The mask keeps the low 53 bits, so a JSON number holdsseed_rexactly. Thesim.startedevent reportsseed_ras itsseed, and every random stream of the run derives fromseed_r. - An output is an object with
pathandrecords. Each entry inrecordsis asummary,timeseries, orfinalrecorder. Asummaryrecorder requires a numeric or integer observable. It computes time-weighted statistics from the warmup time, which is 0 without a warmup, to the final time of the run. The final time is pastdurationwhen the run dispatched work afterdurationwithin the end time limit (section 8.1). Atimeseriesrecorder requires a number or integer observable. It samples at a fixedinterval, or records on every change whenintervalis omitted. Afinalrecorder accepts number, integer, boolean, and string observables. It records the value at the end of the run. An engine must reject a recorder that does not support the observable's declared state type. An output can useasto select its result key. Otherwise, the state path is the result key. - Interval samples are numbered k = 0, 1, 2, and so on. Sample 0 is at the warmup time, which is 0 without a warmup. For k ≥ 1, the sample time depends on how close the warmup is to a whole number of intervals. Let
qbewarmup / interval, computed as one IEEE 754 double division. Letmbeqrounded to the nearest whole number, with halves rounded away from zero. The marginm × 10⁻¹²is the nearest double to 10⁻¹², multiplied bymand rounded to a double. Ifqdiffers frommby at most this margin, samplekis at(m + k) × interval, computed as one IEEE 754 double product. Otherwise, samplekis atwarmup + k × interval: the productk × intervalis rounded to a double, and then the sum is rounded to a double, with no fused multiply-add. Samples continue while the sample time is at most the end time limit (section 8.1). A sample is atdurationonly whendurationis one of these times. A run that stops beforedurationrecords no samples after the stop. The recording work already due at the stop time still runs: the interval samples, and the warmup boundary when the run stops at exactly the warmup time. Work that would change state at that time does not run. When a sample is due at the stop time, that sample is the last one, and it holds the state the run stopped in. For example,duration10 andinterval0.05 give 201 samples, from 0 to 10.duration0.7 andinterval0.1 give 8 samples, and sample 7 is at7 × 0.1, which is 0.7000000000000001. - The product
(m + k) × intervalis the time of stepm + kof a library whose stepnis atn × interval, such as SD boundarynatn × dt(section 8.4) whenintervalequalsdt. The margin accepts a decimal warmup such as 0.3 with interval 0.1, whose quotient is 2.9999999999999996. A sample whose time differs from a step time only by rounding falls before or after that step and records the state on its side. This happens when the sample interval differs from the step: with a step of 0.7 andinterval7, step 90 is at 62.99999999999999, before the sample at 63. It also happens to sample 0 when the warmup andm × intervaldiffer: with warmup 2.1 and a step of 0.7, step 3 is at 2.0999999999999996, before sample 0.
For example, this output records a summary and final value for one path:
{
"path": "teller.utilization",
"records": [
{"type": "summary", "statistics": ["mean", "max"]},
{"type": "final"}
]
}9.1 Recorded result comparison#
schemas/osdl.results.schema.json defines the recorded result exchange format. Result keys use the output as value when present and the output path otherwise. Each key maps to an object whose summary, timeseries, and final members match the configured recorder types.
Recorded values use the observable's declared state type. JSON numbers represent both number and integer state. A final result may use null when no final value is available. Summary statistics are always numbers.
Cross-implementation result comparison applies these rules:
- The defined JSON structure must match.
- JSON object member order does not matter.
- Array order matters.
- Time-series point order matters.
- Numeric values use the precision rule declared by the conformance case.
- A case that pins deterministic sampler output uses bit-exact floating-point values.
10. Event stream#
Engines must emit the typed event stream defined by osdl.events.schema.json. Every event carries the envelope (v, seq, time, type, source). Event payloads, when present, must be JSON objects. seq orders emission within one raw stream. Transports are not specified. In-process callbacks, WebSocket frames, and newline-delimited JSON are conformant transports.
10.1 Current typed events#
The current typed event types are sim.started, sim.progress, sim.completed, sim.error, sim.aborted, entity.created, entity.moved, entity.disposed, state.changed, value.changed, param.changed, metric.updated, agent.transitioned, and message.sent.
A run's raw trace terminates with exactly one terminal frame matching its status: sim.completed {reason} for normal completion, sim.error carrying the structured diagnostic for failure, or sim.aborted {reason} for host or policy abortion.
Libraries can declare additional types in their definitions. Models emit custom types through the emit action. Subscribers must ignore event types they do not understand.
sim.progress, state.changed, and metric.updated are telemetry events. They are valid event-envelope data, but portable event comparison excludes them. Implementations may use different telemetry cadence and content unless an implementation contract requires exact telemetry.
state.changed uses the observable's declared state type. metric.updated uses the same value types as recorded results. It can use null when no recorded value is available.
Engines should let subscribers filter by type and source. They may throttle high-frequency telemetry for remote transports. They must not drop completion, error, abortion, creation, disposal, parameter, agent, message, library, or model events.
10.2 Portable event comparison#
Portable events represent required external behavior. They include lifecycle completion and errors, entity events, parameter changes, events defined by a supported library, and events declared by a model. Recorded results remain the primary cross-implementation output.
Portable event comparison applies these rules:
- Remove telemetry events.
- Remove
seqandwallTimefrom each event. - Preserve event order within a causal identity, such as one entity or agent.
- Allow independent events at the same simulation time to appear in a different order.
- Preserve global order when no safe causal identity is available.
The full event stream remains a diagnostic artifact. An implementation contract can require exact raw trace equality.
11. Views#
Views carry presentation only: canvas positions, sizes, and edge routes keyed by component and connection ids. Views must not affect simulation results. Engines must ignore them; editors should preserve views they do not understand. This separation keeps semantic diffs clean: a layout change touches views, a behaviour change touches model.
12. Library definitions#
A component library is the contract between an engine plugin and every OSDL tool. Its definition document declares the library's namespace, version, and one entry per component type: ports (direction, kind, multiplicity, and the ports each may join), a JSON Schema for params (which may $ref the core schema's value definitions), observable state variables with their scalar types, emitted events, and a required prose description: the semantic contract, written for humans and language models alike.
From a library definition alone, with no engine present, a tool can render palettes, generate parameter forms, validate documents (phase two), power autocompletion, and prompt a language model with precise component semantics.
The standard des, abm, sd, and data libraries are optional conformance modules in libraries/. An implementation declares support for a library namespace and version outside an OSDL document. It must run that library's conformance suite when it claims support. Supporting one library does not require support for another library. Third-party libraries use their own namespaces.
13. Versioning and extensibility#
- The
osdlfield pins the exact spec version. Tools must reject documents declaring versions they do not implement. - v0.x versions make no compatibility promises. This draft remains versioned as
0.1. metadataobjects are the extension escape hatch, allowed on most objects. Keys should be reverse-DNS namespaced. Metadata must not affect simulation semantics; anything that does belongs in the schema, a library definition, or a spec proposal.- Component libraries version independently of the specification by semantic versioning.
ROADMAP.md records planned post-1.0 behavior and version policy.