{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://earthsciml.org/schemas/esm/1.3.0/esm.schema.json",
"title": "ESM Format",
"description": "EarthSciML Abstract Syntax Tree Format — v1.3.0 adds two OPTIONAL `solver` fields (esm-spec §2.2): `external`, a reference to a run-configuration document that EarthSciAST resolves but never opens (§2.2.6), and `time_span`, the interval the document is meant to be simulated over, as numbers in seconds or RFC 3339 UTC timestamps (§2.2.7). Both are advisory and change no flattened system; a document declaring esm below 1.3.0 that carries either is rejected (`solver_external_version_too_old` / `solver_time_span_version_too_old`). v1.2.0 adds an OPTIONAL declared `units` string on a `const` expression node (esm-spec §4.8.5): the unit the constant's value is in, so a conversion constant such as `{\"op\": \"const\", \"args\": [], \"value\": 0.44704, \"units\": \"m*h/(mi*s)\"}` makes its equation dimensionally checkable. Purely additive: `units` is legal on no other node, and a document declaring esm below 1.2.0 that carries it is rejected with `const_units_version_too_old`. v1.1.0 renames the unified query node from `aggregate` to `faq`, the Functional Aggregate Query it has always been (docs/content/rfcs/faq-node-rename.md). `aggregate` names only one of the node's specializations: it also joins, filters, and — under `bool_and_or` with `distinct` — produces an index set rather than an array, reducing nothing. `faq` is the canonical tag; `aggregate` is accepted as a DEPRECATED ALIAS, normalized to `faq` at load with the warning `deprecated_op_alias`, and REMOVED at esm 2.0.0. The text surface is unchanged: the head keyword there is the \u2295-word (`sum`/`prod`/`max`/`min`/`any`), not the node name. The `arrayop` alias — nominally removed at 0.8.0 but still live in all five bindings — is removed for real. Also at v1.1.0: the top-level `solver` block. (v1.0.0) — a `faq`'s `join` clause carries the optional `syms`, naming the two RANGE SYMBOLS its `on` pairs are read at, so a relation can be joined to ITSELF: two ranges over one index set, whose key columns' shared axis cannot say which side is which (CONFORMANCE_SPEC §5.5.8, docs/content/rfcs/self-join-two-ranges-over-one-index-set.md). Purely additive — every document written before it stays valid and unchanged, which is why it lands without a version bump; see that note's §4. v1.0.0 — a language-agnostic JSON format for Earth system model components, their composition, and runtime configuration. v1.0.0 is a clean break with no deprecation path and no compatibility shims (docs/content/rfcs/unified-variable-model.md): the five declared variable types collapse to TWO. `unknown` is a quantity the solver solves for — its behavior is given by EQUATIONS and never by a field on the variable — and `parameter` is a quantity supplied to the solver, carrying a number or a `distribution` plus an optional `update` block saying when and from what it refreshes. Removed: `state` and `observed` (with the `expression` field — an observed variable becomes an unknown plus a bare-variable-LHS equation); `brownian` (with `noise_kind` / `correlation_group` — a noise source is a parameter with a `distribution` and `update.kind: \"wiener\"`, correlated noise being ONE vector-valued parameter whose distribution carries a `cov` matrix, which closes the gap the 0.x schema explicitly deferred); `discrete` (with `refresh` and the `RefreshTrigger` def — a refreshing input is a parameter with a `schedule` / `data` / `remesh` update); the `discrete_parameters` event lists and the event `functional_affect` (parameter mutation moves onto the parameter itself as a `condition` / `crossing` update carrying an `expression`, a `from` binding, or a `handler`; events now affect UNKNOWNS only); and the `data_loaders` COMPONENT kind together with `DataLoader.variables` (top-level `data_sources` is now a pure registry of ingest configuration — source, temporal, select, record_filter, extent, reader_options, determinism — that parameters draw from via `update.from`; a data source is no longer a coupling endpoint, a subsystem, or a scoped-name path root). Everything the solver needs is DERIVED rather than declared — which unknowns are ODE states, observed, or algebraic, and which parameters are Brownian, discrete, sampled, or constant — and every binding exposes the same classification functions to derive it (esm-spec §6.3.1). v0.9.0 changes no on-disk shape: it replaces the Option A (always-expanded) template round-trip with Option B (reference-preserving; esm-spec §9.6.4, docs/content/rfcs/out-of-line-expression-templates.md). Template references survive load and parse-then-emit; emit materializes each component's referenced templates into its `expression_templates` registry (authored entries first in authored order, materialized entries after in lexicographic UTF-8 name order; registry keys may be dotted post-rename names); eager references (target-bearing, esm-spec §9.6.4 rule 3) still expand at load, so no rewrite-target op survives inside a reference; `emit ∘ load` is a byte-wise fixed point; emitted documents carrying surviving references or materialized registries declare `esm: 0.9.0` or later. v0.8.0 is a clean break that removes all bespoke spatial-grid machinery in favor of expressing grid geometry directly with the unified Functional Aggregate Query (`faq`) IR (RFC semiring-faq-unified-ir), and retains no backward-compatibility shims. Removed: the top-level `grids`, `staggering_rules`, and `discretizations` blocks; the `Grid` / `GridExtent` / `GridMetricArray` / `GridMetricGenerator` / `GridConnectivity` / `GridCRS` defs; the entire stencil-template discretization rule grammar (`Discretization`, `DiscretizationVariant`, `MultiOutputStencilRule`, `DiscretizationRef`, `GridDiscretizationDescriptor`, and the `Rule` / `PatternNode` / `NeighborSelector` / `StencilEntry` / `RuleBinding` / `BoundaryPolicy` / `BoundaryPolicySpec` / `GhostWidth` / `GhostVarDecl` / `RuleRegion` / `RuleGuard` machinery, including `Equation.region`); all regridding configuration (`Model.regrid`, `RegridSpec`, `Interface.regridding`); the `Domain.spatial` / `SpatialDimension` / `CoordinateTransform` geometry block and the deprecated domain-level `boundary_conditions`; the `DataLoader.grid` / `DataLoader.mesh` descriptors and the `DataLoaderMesh` def; and the `grid_discretization_descriptor` document kind with its `grid_refs` test/example fields. Grid geometry — coordinates, extents, spacing, CRS parameters, connectivity, and metric arrays — is now ordinary data: loaded from a `data_loaders` primitive or declared as variables/parameters, with topology and metrics constructed declaratively as `faq` nodes (the `intersect_polygon` kernel leaf remains for polygon clipping). Iteration domains are declared once in the document-scoped `index_sets` registry. Regridding is expressed as an ordinary coupling expression between two variables. Earlier additive features are retained: the `integral` AST op (PIDEs), array-or-single `plots.y`, sampled `function_tables` + `table_lookup`, in-file `expression_templates` + `apply_expression_template`, and the closed `enums` + `fn` / `enum` ops. The template-library RFC (docs/content/rfcs/template-library-imports.md; esm-spec §9.7) adds cross-file template sharing at esm 0.8.0: template-library files (top-level `expression_templates`), ordered `expression_template_imports` with §4.7 reference semantics, and load-time integer `metaparameters` admissible in `index_sets` sizes, `faq` dense ranges, and `makearray` regions — all resolved and folded at load, before validation and before the §9.6.3 rewrite fixpoint.",
"type": "object",
"required": [
"esm",
"metadata"
],
"additionalProperties": false,
"anyOf": [
{
"required": [
"models"
]
},
{
"required": [
"reaction_systems"
]
},
{
"required": [
"data_sources"
]
},
{
"required": [
"expression_templates"
]
},
{
"required": [
"coupling_roles"
]
}
],
"properties": {
"esm": {
"type": "string",
"description": "Format version string (semver).",
"pattern": "^\\d+\\.\\d+\\.\\d+$"
},
"metadata": {
"$ref": "#/$defs/Metadata"
},
"models": {
"propertyNames": { "$ref": "#/$defs/Identifier" },
"type": "object",
"description": "ODE-based model components, keyed by unique identifier. Each component may be defined inline or included by reference to an external ESM file containing exactly one top-level model (esm-spec.md §4.7).",
"additionalProperties": {
"oneOf": [
{
"$ref": "#/$defs/Model"
},
{
"$ref": "#/$defs/SubsystemRef"
}
]
}
},
"reaction_systems": {
"propertyNames": { "$ref": "#/$defs/Identifier" },
"type": "object",
"description": "Reaction network components, keyed by unique identifier. Each component may be defined inline or included by reference to an external ESM file containing exactly one top-level reaction system (esm-spec.md §4.7).",
"additionalProperties": {
"oneOf": [
{
"$ref": "#/$defs/ReactionSystem"
},
{
"$ref": "#/$defs/SubsystemRef"
}
]
}
},
"data_sources": {
"propertyNames": { "$ref": "#/$defs/Identifier" },
"type": "object",
"description": "Document-scoped registry of external data sources, keyed by name. A data source is INGEST CONFIGURATION, not a component: it says where bytes live and how to decode, slice, and filter them, and it exposes no variables of its own. A model consumes one by declaring a parameter whose `update` names the source and binds a `file_variable` from it. The shared parts stay here because their guarantees are source-wide and cannot be stated per-parameter: `record_filter` computes the surviving-record mask ONCE and applies it to every parameter drawing from this source, which is what makes it impossible for two columns of one points table to fall out of alignment, and `extent` binds ONE metaparameter from that single shared record count.",
"additionalProperties": {
"$ref": "#/$defs/DataSource"
}
},
"enums": {
"propertyNames": { "$ref": "#/$defs/Identifier" },
"type": "object",
"description": "File-local symbol-to-integer mappings used by the 'enum' AST op to make categorical lookups cross-binding-portable. Each entry is an enum name; its value is an object mapping symbolic names (strings) to integers — any integer, negative, zero or positive, since an enum member is a categorical code rather than a 1-based position. Two .esm files may declare an enum of the same name with different mappings; enums are file-local and never merged across files. See esm-spec.md §9.3.",
"additionalProperties": {
"$ref": "#/$defs/EnumDeclaration"
}
},
"coupling": {
"type": "array",
"description": "Composition and coupling rules.",
"items": {
"$ref": "#/$defs/CouplingEntry"
}
},
"domain": {
"$ref": "#/$defs/Domain",
"description": "The single temporal domain shared by every component in the document (temporal extent + numeric representation). A document has at most one domain; all spatial models live on it, and 0-D models simply have scalar-shaped variables."
},
"function_tables": {
"propertyNames": { "$ref": "#/$defs/Identifier" },
"type": "object",
"description": "Component-scoped sampled function tables (v0.4.0). Each entry declares ordered named axes plus a literal nested-array data block, optionally tagged with output names; the `table_lookup` AST op references a table by id, supplies a per-axis input-coordinate expression map, and selects which output to return. Tables are syntactic sugar over `interp.linear` / `interp.bilinear` / `index`: a `table_lookup` MUST be bit-equivalent to the equivalent inline-const lookup. See esm-spec.md §9.5 and docs/rfcs/sampled-tables.md.",
"additionalProperties": {
"$ref": "#/$defs/FunctionTable"
}
},
"index_sets": {
"propertyNames": { "$ref": "#/$defs/Identifier" },
"type": "object",
"description": "Document-scoped registry of named index sets (RFC semiring-faq-unified-ir §5.2), keyed by name — the single, document-level declaration site for every iteration domain (grid axes, categorical dimensions, data-derived sets) shared by all models in the document. A `faq` range references one by name as { \"from\": <name> }. Each entry is an interval (dense axis), categorical enumeration, data-derived set, or ragged / dependent inner set. A reference resolves by name to exactly one entry; resolvers MUST error on an undeclared name.",
"additionalProperties": {
"$ref": "#/$defs/IndexSet"
}
},
"coordinates": {
"propertyNames": { "$ref": "#/$defs/Identifier" },
"type": "object",
"description": "Document-scoped, OPTIONAL registry of coordinate variables (RFC streaming-output-sinks §8), keyed by name. Purely additive: a document without it validates and emits exactly as before (bare integer axes). Each entry marks an existing data array — a model unknown or parameter referenced BY NAME (including a parameter fed from a `data_sources` entry) (exactly as a ragged `IndexSet` references its `offsets`/`values` factors), or an inline literal `values` vector — as a physical coordinate and attaches CF metadata (`standard_name`, `units`, optional `axis`). The coordinate's SHAPE is read from its source, so it is NOT attached to any single axis: this is the CF coordinate data model, covering rectilinear (1-D monotonic → CF dimension coordinate), unstructured (1-D over a shared dimension → CF auxiliary coordinate) and curvilinear (2-D `lat(y,x)`/`lon(y,x)` → auxiliary coordinate) grids under one rule. A streaming writer derives each data variable's CF `coordinates` attribute mechanically: every coordinate whose source DIMENSIONS (by identity, NOT by length) are a subset of the data variable's dimensions applies to it.",
"additionalProperties": {
"$ref": "#/$defs/Coordinate"
}
},
"solver": {
"$ref": "#/$defs/Solver"
},
"expression_templates": {
"propertyNames": { "$ref": "#/$defs/Identifier" },
"type": "object",
"description": "Top-level rewrite rules / templates — the payload of a template-library file (esm-spec §9.7.1). Only valid in a library file (which carries no models/reaction_systems/data_loaders/coupling/domain, `template_import_not_library` when imported otherwise); component-local templates stay inside their model/reaction_system (§9.6.1). Arrives at esm 0.8.0 (`template_import_version_too_old`).",
"additionalProperties": {
"$ref": "#/$defs/ExpressionTemplate"
}
},
"expression_template_imports": {
"type": "array",
"description": "Ordered imports of template-library files at document top level — only valid in a library file layering on other libraries (esm-spec §9.7.2). Models and reaction systems carry their own `expression_template_imports` field.",
"items": {
"$ref": "#/$defs/TemplateImport"
}
},
"metaparameters": {
"$ref": "#/$defs/Metaparameters"
},
"coupling_roles": {
"propertyNames": { "$ref": "#/$defs/Identifier" },
"type": "object",
"description": "Coupling-library formal component roles (esm-spec §10.9). Present only in a coupling-library file, which pairs it with a role-scoped `coupling` array and declares no models/reaction_systems/data_loaders/domain/index_sets/metaparameters/expression_templates (enforced by the resolver as `coupling_library_illegal_payload`). Presence of this key is the sole positive identifier of the coupling-library file kind. Each entry is a role descriptor carrying an optional human-readable `description`; roles are formal parameters (names, not types), bound to actual components at a `coupling_import` (esm-spec §10.10).",
"additionalProperties": {
"type": "object",
"additionalProperties": false,
"properties": {
"description": {
"type": "string"
}
}
}
}
},
"$defs": {
"Identifier": {
"type": "string",
"pattern": "^[^\\x00-\\x1f\\x7f]*$",
"description": "A declared name: a component, variable, species, parameter, index set, data source, enum, table, template or metaparameter key. It MUST NOT contain a NUL or any other C0 control character or DEL (esm-spec §4.9.1.2): such a name cannot be written in the expression syntax, and a binding that interns names (Julia `Symbol`) cannot represent a NUL at all."
},
"Metadata": {
"type": "object",
"description": "Authorship, provenance, and description.",
"required": [
"name"
],
"additionalProperties": false,
"properties": {
"name": {
"type": "string",
"description": "Short identifier for the model configuration."
},
"description": {
"type": "string"
},
"authors": {
"type": "array",
"items": {
"type": "string"
}
},
"license": {
"type": "string"
},
"created": {
"type": "string",
"format": "date-time",
"pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?(Z|[+-]\\d{2}:\\d{2})$",
"description": "ISO 8601 creation timestamp. The pattern duplicates `format: date-time` because `format` is an annotation, not an assertion, in JSON Schema — validators ignore it unless separately configured, so the pattern is what makes the constraint portable across bindings."
},
"modified": {
"type": "string",
"format": "date-time",
"pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?(Z|[+-]\\d{2}:\\d{2})$",
"description": "ISO 8601 last-modified timestamp."
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"references": {
"type": "array",
"items": {
"$ref": "#/$defs/Reference"
}
},
"system_class": {
"type": "string",
"enum": [
"ode",
"dae"
],
"description": "Diagnostic stamped by discretize(): whether the resolved system is a pure ODE or a DAE (RFC §12)."
},
"dae_info": {
"type": "object",
"description": "Diagnostic stamped by discretize(): algebraic-equation accounting (RFC §12).",
"properties": {
"algebraic_equation_count": {
"type": "integer"
},
"per_model": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
},
"discretized_from": {
"type": "object",
"description": "Diagnostic stamped by discretize(): identifies the source document this was discretized from (RFC §12).",
"properties": {
"name": {
"type": "string",
"description": "The metadata.name of the source document."
}
}
},
"x_esd": {
"type": "object",
"description": "Reserved extension point for downstream-catalog machine-readable metadata (e.g. the EarthSciDiscretizations rule-library catalog). Free-form JSON: the schema validates only that this is an object. The core spec NEVER interprets, validates, or transforms its contents — core tooling MUST NOT assign meaning to them and MUST preserve them across parse → emit like any other metadata field. Downstream catalogs define and version their own conventions inside it (esm-spec §3)."
}
}
},
"Reference": {
"type": "object",
"description": "Academic citation or data source reference.",
"additionalProperties": false,
"properties": {
"doi": {
"type": "string",
"pattern": "^10\\.\\d{4,9}/\\S+$",
"description": "DOI in the standard `10.<registrant>/<suffix>` form."
},
"citation": {
"type": "string"
},
"url": {
"type": "string",
"format": "uri",
"pattern": "^[a-zA-Z][a-zA-Z0-9+.-]*://[^\\s]+$|^(mailto|urn):[^\\s]+$",
"description": "Absolute URI. The pattern duplicates `format: uri` because `format` is an annotation, not an assertion, in JSON Schema."
},
"notes": {
"type": "string"
}
}
},
"Expression": {
"description": "Mathematical expression: a number literal, a variable/parameter reference string, or an operator node.",
"oneOf": [
{
"type": "number"
},
{
"type": "string"
},
{
"$ref": "#/$defs/ExpressionNode"
}
]
},
"ExpressionNode": {
"type": "object",
"description": "An operation in the expression AST.",
"required": [
"op",
"args"
],
"properties": {
"op": {
"type": "string",
"minLength": 1,
"pattern": "^([A-Za-z_][A-Za-z0-9_.]*|[-+*/^<>=!]+)$",
"description": "Operator name. TWO TIERS (esm-spec §4.2). (1) The CLOSED evaluable-core set — every binding's evaluator implements each one directly: `+ - * / ^` and `pow` (the word spelling of `^`), the comparisons/booleans (`> < >= <= == != and or not`), the elementary functions (`exp log log10 sqrt abs sign sin cos tan asin acos atan atan2 sinh cosh tanh asinh acosh atanh min max floor ceil`), `ifelse`, the calculus form-ops `D` and `ic` (structural / equation-LHS use only), `Pre`, the boolean literals `true` and `false`, and the array/query ops (`faq makearray index broadcast reshape transpose concat skolem rank argmin argmax intersect_polygon polygon_intersection_area fn enum const table_lookup apply_expression_template`). (2) The OPEN rewrite-target tier — ANY other identifier: a spatial `D` on a right-hand side, the optional sugar ops `grad`/`div`/`laplacian`/`integral`, or a user op such as `godunov_hamiltonian`. A rewrite-target op carries NO evaluator implementation and MUST be eliminated by a rewrite rule (§9.6) before evaluation. Loading is permissive — a file MAY load with rewrite-target ops still present (e.g. a coupling/scoping example that never simulates) — but one reaching evaluation/compilation without being lowered is rejected with `unlowered_operator`. The `pattern` only rejects malformed strings — it does NOT enforce membership in the core set, so the open tier stays expressible. The evaluable-core set is the ONLY set the format privileges. The array/query node `faq` is a FUNCTIONAL AGGREGATE QUERY (docs/content/rfcs/semiring-faq-unified-ir.md): a semiring reduction of a body over named index sets, carrying joins, filters and set semantics, so under `bool_and_or` + `distinct` it produces an INDEX SET rather than an array and reduces nothing. DEPRECATED ALIAS: `aggregate` is the pre-1.1.0 spelling of `faq`. A loader MUST accept it, MUST normalize the node to `faq` before validation so that nothing downstream of the loader sees the alias, and MUST report the warning diagnostic `deprecated_op_alias` once per document per alias. It is REMOVED at esm 2.0.0 (docs/content/rfcs/faq-node-rename.md). The older `arrayop` spelling is NOT accepted. It was removed at 0.8.0 and is rejected BY NAME with the hard error `removed_op` — NOT left to the open tier: `arrayop` is a well-formed identifier, so the open rewrite-target tier would otherwise admit it and the document would load silently, failing much later as `unlowered_operator`, or never. A loader MUST also reject a document that spells `faq` while declaring esm < 1.1.0 (`faq_version_too_old`), the same version gate the top-level `solver` block follows; the gate reads the AUTHORED form, so a pre-1.1.0 document carrying the `aggregate` alias stays legal and is normalized with its declared version raised to the 1.1.0 floor.",
"$comment": "The evaluable-core set is normative and closed; each binding pins it as its evaluator's op registry. It is documented (not enum-enforced) so the open rewrite-target tier remains expressible. grad/div/laplacian/integral are NOT core — they are optional author sugar lowered by rewrite rules (esm-spec §9.6.8); the discretization rule std-lib lives in ../earthscidiscretizations, not this repo."
},
"id": {
"type": "string",
"description": "Stable node identity (RFC semiring-faq-unified-ir §6.1): an optional, author-assigned identifier that makes this expression node addressable as a vertex in the inter-node dependency DAG the partition pass walks. Its primary use is to be the referent of a derived index set: an `index_sets` entry of kind \"derived\" names, via `from_faq`, the index-set-producing `faq` node that materializes it — and it names it by this id. When present it MUST be unique among the expression nodes of its DOCUMENT — `index_sets` is a document-scoped registry, so a `from_faq` in it resolves against every model's nodes, and per-model uniqueness would leave a cross-model reference ambiguous. The build-time reference-resolution pass errors on a duplicate id and on a `from_faq` that names no node in the document. Absent ⇒ the node is addressed only by its structural path and cannot be the target of a `from_faq`. Purely additive: a file using no `id` validates and resolves exactly as before."
},
"expect_cadence": {
"type": "string",
"enum": [
"const",
"discrete",
"continuous"
],
"description": "Optional author assertion on this node's cadence class, checked by the dependency-partition pass (RFC semiring-faq-unified-ir §6.1; CONFORMANCE_SPEC.md §5.7). A diagnostic/test hook ONLY — it changes no semantics. The pass derives every node's class from the data-dependency DAG (`class(node) = max` over inputs; `const ⊏ discrete ⊏ continuous`); when `expect_cadence` is present the pass errors if the DERIVED class disagrees with it. \"const\" = never changes, folded into the artifact (parameter / literal); \"discrete\" = changes only at discrete events, recomputed by the per-event handler (a `discrete` variable, e.g. loaded met / reloadable mesh); \"continuous\" = changes every step, evaluated in the hot per-step tree (integrated state `u`, or an explicit continuous-`t` forcing). Absent ⇒ no assertion. Purely additive: a file using no `expect_cadence` validates and partitions exactly as before."
},
"args": {
"type": "array",
"description": "Operand list. For most ops these are sub-expressions. Array ops use args for the input array operands (faq, broadcast, index, reshape, transpose, concat). makearray has no natural args and uses an empty array. For `D` (esm-spec §4.2 \"Arity of `D`\"): `args[0]` is always the differentiated operand; a STRUCTURAL `D` (`wrt` \"t\", or `wrt` absent) is strictly unary, while a REWRITE-TARGET `D` (spatial `wrt`) MAY carry an unbounded number of TRAILING AUXILIARY OPERANDS after `args[0]` — the per-face boundary/halo data a discretization rule binds and consumes (§9.6.8). Trailing operands carry NO evaluator semantics and no per-position meaning assigned by this format; they are matched positionally by the consuming rule.",
"items": {
"$ref": "#/$defs/Expression"
},
"minItems": 0
},
"wrt": {
"type": "string",
"description": "Differentiation variable for the `D` op: the time variable `t` (structural, equation-LHS use) OR a spatial axis (e.g. \"x\", \"lon\"). Absent means `t`. A `D` with a spatial `wrt`, or any `D` appearing in a right-hand-side expression position, is a rewrite-target (esm-spec §9.6.8): it MUST be lowered to a stencil by a discretization rule before evaluation, else `unlowered_operator`. `wrt` also fixes this node's ARITY (esm-spec §4.2 \"Arity of `D`\"): `wrt` \"t\" (or absent) is STRICTLY UNARY, enforced by the `D` clause of this object's `allOf`; a spatial `wrt` MAY carry unbounded trailing auxiliary operands in `args[1..]`."
},
"dim": {
"type": "string",
"description": "Scalar field naming a spatial axis (e.g. \"x\", \"y\", \"z\"). Carried by rewrite-target differential-operator sugar (`grad`/`div`/`laplacian`) and admissible on any open-tier rewrite-target op; it is an ordinary axis-naming scalar field with NO privileged status. A `dim` value names a spatial coordinate STRUCTURALLY, independent of the enclosing `op` (esm-spec §4.9.1), and confers no dimensional rule on its op (the op's dimension is UNDETERMINABLE until lowered, §4.8.3/§4.8.4). PREFER `D` with `wrt` set to the axis. Custom rewrite-target ops MAY instead carry scheme parameters in `attrs`."
},
"attrs": {
"type": "object",
"description": "Optional named scalar attributes for an OPEN rewrite-target op (esm-spec §4.2). Mirrors the role of the fixed `dim`/`side`/`wrt`/`var` slots that core ops use, but is open: a custom op (e.g. `godunov_hamiltonian`) carries its scheme parameters here. In a rewrite rule's `match`, an `attrs.<key>` whose value is a bare param name binds that param to the matched literal (esm-spec §9.6.1). Evaluable-core ops MUST NOT use `attrs`."
},
"var": {
"type": "string",
"description": "Integration variable for the integral operator: the name of the spatial dimension being integrated over (e.g., \"x\")."
},
"lower": {
"$ref": "#/$defs/Expression",
"description": "Lower integration bound for the integral operator. Any Expression: a numeric literal, a parameter reference, or an AST subtree. For a whole-domain integral both lower and upper are constants."
},
"upper": {
"$ref": "#/$defs/Expression",
"description": "Upper integration bound for the integral operator. Any Expression: a numeric literal, a parameter reference, the integration variable name (string) for a cumulative/partial integral, or an AST subtree."
},
"output_idx": {
"type": "array",
"description": "For faq: the result's index signature. Each entry is either a string (a symbolic index variable like \"i\", \"j\") or the integer 1 (a literal singleton dimension for reshape/broadcast). Mirrors SymbolicUtils.ArrayOp.output_idx.",
"items": {
"oneOf": [
{
"type": "string"
},
{
"type": "integer",
"const": 1
}
]
}
},
"expr": {
"$ref": "#/$defs/Expression",
"description": "For faq: the scalar body evaluated at each index point. May reference index symbols declared in output_idx as well as additional (contracted) index symbols. Mirrors SymbolicUtils.ArrayOp.expr. A causal SELF-REFERENCE is admitted here and nowhere else: when this `faq` is the right-hand side of the equation that defines an array-shaped unknown V, the body may read `index(V, k - c)` — V itself, at a strictly earlier position along ONE of this node's output axes — and V is then materialized cell by cell, that axis outermost and ascending, each cell published before the axis advances. That is the format's only spelling for a recurrence; no `scan` / `fold` / `recur` operator exists and a binding MUST NOT add one. The recurrence, its axis and its maximum lag are all DERIVED from the read, so nothing is declared and this schema gains no field: what makes a self-read legal is a constraint between this node and the equation containing it, which JSON Schema cannot express, so it is enforced by structural validation (`recurrence_not_wellfounded`, `recurrence_unsupported_form`). See esm-spec §4.3.1.1, CONFORMANCE_SPEC §5.19, and docs/content/rfcs/causal-self-reference-recurrence.md."
},
"reduce": {
"type": "string",
"description": "For faq: the reduction operator applied to any index symbol that appears in expr but not in output_idx. Default is \"+\". This names only the ⊕ operator; it is a shorthand retained for files that omit \"semiring\" (⊕ = reduce, ⊗ = \"*\"). When \"semiring\" is present it supersedes \"reduce\".",
"enum": [
"+",
"*",
"max",
"min"
],
"default": "+"
},
"semiring": {
"type": "string",
"description": "For faq: the named semiring (⊕, ⊗) that parameterizes the reduction (RFC semiring-faq-unified-ir §5.1). A closed, exhaustive registry — adding a semiring is a spec change, not a per-file extension. Absent ⇒ \"sum_product\", which reproduces today's einsum / sum-of-products semantics exactly (the strict-superset promise). The ⊕ operator, the ⊗ operator, and BOTH identity elements (the value of an empty ⊕-reduction and an empty ⊗-product) are fixed by the registry table and MUST NOT be written into the file: sum_product (+,0;×,1), max_product (max,-∞;×,1), min_sum (min,+∞;+,0), max_sum (max,-∞;+,0), bool_and_or (∨,false;∧,true).",
"enum": [
"sum_product",
"max_product",
"min_sum",
"max_sum",
"bool_and_or"
],
"default": "sum_product"
},
"ranges": {
"type": "object",
"description": "For faq: optional map from index symbol name to the range it iterates over. Each value is EITHER (a) a dense integer tuple — a 2-element array [start, stop] (unit step) or a 3-element array [start, step, stop], as today, mirroring SymbolicUtils.ArrayOp.ranges — entries MAY be metaparameter expressions folded to concrete integers at load (esm-spec §9.7.6); OR (b) a reference to a declared index set (RFC semiring-faq-unified-ir §5.2): an object { \"from\": <index_sets key> }, optionally with \"of\": [parent index names] for a ragged / dependent inner set (e.g. the edges of cell \"i\"). Indices not present are inferred from the domain / operand shapes at runtime.",
"additionalProperties": {
"oneOf": [
{
"type": "array",
"items": {
"$ref": "#/$defs/MetaparameterExpression"
},
"minItems": 2,
"maxItems": 3
},
{
"type": "object",
"additionalProperties": false,
"required": [
"from"
],
"properties": {
"from": {
"type": "string",
"description": "Name of a declared index set: a key in the document-scoped top-level index_sets registry. The resolver MUST error on an undeclared name; no implicit interval is inferred, so a typo cannot silently become an empty set."
},
"of": {
"type": "array",
"description": "Parent index name(s) for a ragged / dependent inner set: the enumeration depends on these outer indices (e.g. { \"from\": \"edges_of_cell\", \"of\": [\"i\"] } iterates the POSITIONS k in 1…offsets[i] of cell i's edges, and the body gathers each edge as index(values, i, k); esm-spec §4.3.1 \"Ragged ranges\").",
"items": {
"type": "string"
}
}
}
}
]
}
},
"join": {
"type": "array",
"description": "For faq: optional value-equality combination of factors by key columns — an inner equi-join (RFC semiring-faq-unified-ir §5.3), subsuming ESI join and making connectivity gathers first-class. Each entry is a join clause whose \"on\" lists one or more key-column pairs [left, right]; a ⊗-product term is contributed only for index combinations whose key columns are equal on EVERY listed pair, and an unmatched row contributes the additive identity (the empty ⊕-reduction value), adding nothing under any semiring. Inner-only — there is no outer/left variant; many-to-many is defined, not an error (m·n product terms, each a ⊗-term into the enclosing ⊕-reduction); key columns must be exact-equality types (integer IDs or categorical members compared by Unicode code point) — floating-point join keys are forbidden. Absent ⇒ factors combine only by shared index name (positional einsum), exactly as today. A key column may name a loop symbol, an index set, or a genuine 1-D DATA COLUMN, and the resolved match set DRIVES enumeration rather than merely testing it (CONFORMANCE_SPEC §5.5.8).",
"items": {
"type": "object",
"additionalProperties": false,
"oneOf": [
{
"required": [
"on"
]
},
{
"required": [
"overlap"
]
}
],
"dependentRequired": {
"syms": [
"on"
]
},
"properties": {
"on": {
"type": "array",
"description": "The key-column pairs to equi-join on. Each pair is a 2-element array [left, right] naming the two factor key columns whose values must compare equal. At least one pair is required. Each name resolves, in this order (CONFORMANCE_SPEC §5.5.8): a LOOP SYMBOL of this node, or the INDEX SET one of its ranges draws {from} — key values are that set's declared members / integer IDs; otherwise a DATA COLUMN, a declared 1-D variable whose single shape index set names one of this node's ranges, whose values are read as data (the relational-port spelling: one table's sourceTypeID column against another's). Listing several pairs over the same two loop symbols is ONE composite key — a combination is admitted iff every listed pair agrees, i.e. tuple equality on the canonical skolem tuple, not several independent gates. The match set is built ONCE per node and DRIVES enumeration exactly as an `overlap` gate's candidate set does, so the contraction costs O(|matches|) rather than O(|left|*|right|), and an output position with no match takes the semiring identity.",
"minItems": 1,
"items": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 2,
"maxItems": 2
}
},
"syms": {
"type": "array",
"description": "The two RANGE SYMBOLS this clause's `on` pairs are read at, as [left, right] — the answer to the one question a pair of column names cannot settle. A key column is normally resolved to a loop symbol through its declared AXIS, which is unique for a join between two distinct relations; when a node draws ONE index set with SEVERAL of its ranges (a relation joined to ITSELF: the prefix-scan shape of esm-spec §4.3.1, now with a value-equality gate instead of a `filter`) the axis names two or more candidate symbols and the pair alone does not say which side is which. Absent ⇒ the DEFAULT side assignment: with exactly two candidates the left key is read at the earlier one in canonical range order (`output_idx` order, then the contracted symbols ascending) and the right key at the later; with three or more, resolution is REFUSED and this field is required. Present ⇒ every pair in the clause is read left-at-syms[0], right-at-syms[1], and a key whose axis the named symbol does not draw — or which names a different range symbol outright — is a build error. Both entries MUST name ranges of this node. These name symbols the node BINDS, not variable references, so flattening's dot-namespacing and `variable_map` renaming leave them alone (CONFORMANCE_SPEC §5.5.8).",
"minItems": 2,
"maxItems": 2,
"items": {
"type": "string"
}
},
"overlap": {
"type": "object",
"description": "Spatial OVERLAP gate — the alternative to an `on` value-equality gate (CONFORMANCE_SPEC §5.5). Replaces uniform-grid bin-equality with envelope candidacy: a contracted (src_pos, tgt_pos) tuple is admitted iff the two range positions are in a broad-phase candidate set computed once from two envelope factor arrays. The narrow phase (exact rectangle / polygon test) stays as the `faq`'s `filter`; this gate is ONLY the conservative broad phase, so the materialized result is identical to the full-product path. The candidate set also DRIVES enumeration of the `faq` it is attached to — ANY `faq`, an ordinary dense reduction as much as an index-set-producing `distinct` producer, and either side may be the skolemised/output one; an output position with no candidate pair is filled with the semiring identity (CONFORMANCE_SPEC §5.5.6 Join admission).",
"additionalProperties": false,
"required": [
"src_env",
"tgt_env"
],
"properties": {
"src_env": {
"type": "array",
"description": "The QUERY-side envelope factors: const-array factor names interpreted as per-position envelopes. Arity 4 → rectangles [xmin, ymin, xmax, ymax]; arity 2 → points [x, y] (degenerate envelope (x, y, x, y)); arity 1 → a [pos, verts, coord] 3-D ring factor reduced to its axis-aligned bbox. These factors share a 1-D shape index set which names the source loop symbol.",
"minItems": 1,
"items": {
"type": "string"
}
},
"tgt_env": {
"type": "array",
"description": "The INDEXED (cell) side envelope factors, e.g. [\"W\",\"S\",\"E\",\"N\"]. Same arity rules as src_env, chosen independently. These factors share a 1-D shape index set which names the target loop symbol.",
"minItems": 1,
"items": {
"type": "string"
}
},
"eps": {
"type": "number",
"default": 0.0,
"minimum": 0.0,
"description": "Inflates BOTH envelopes of a pair OUTWARD by eps (xmin−=eps, ymin−=eps, xmax+=eps, ymax+=eps) before the intersection test. The broad-phase predicate is a CLOSED per-axis AABB test (edge-touching admitted). Absent ⇒ 0.0."
}
}
}
}
}
},
"filter": {
"$ref": "#/$defs/Expression",
"description": "For faq: optional boolean predicate Expression that restricts which index combinations contribute a ⊗-product term to the reduction (RFC semiring-faq-unified-ir §5.3 / §7.2). May reference any index symbol in scope (an entry of output_idx or a contracted index). Combinations for which the predicate evaluates false contribute the additive identity (the empty ⊕-reduction value) — the explicit way to express a guarded sum or a \"keep unmatched with a default\", as opposed to a join mode."
},
"distinct": {
"type": "boolean",
"default": false,
"description": "For faq: when true, the node has set semantics (dedup) and is index-set-producing — it materializes a data-derived index set rather than an array (RFC semiring-faq-unified-ir §5.5). Only meaningful under the `bool_and_or` semiring (the relational specialization, §5.1); combined with `key`, it enumerates the unique Skolem terms (e.g. the unique edges discovered from a face→vertex relation) and exposes the result as a `kind:\"derived\"` index set (§5.2) that a downstream geometric `faq` consumes. The output order is fixed by the normative determinism rules (§5.7): sort by the total tuple order, then drop adjacent duplicates — never first-seen / insertion order. Absent ⇒ false (ordinary array-producing reduction), exactly as today."
},
"key": {
"$ref": "#/$defs/Expression",
"description": "For faq: optional Skolem term — a deterministic, content-addressed key naming each member an index-set-producing (`distinct`) node emits (RFC semiring-faq-unified-ir §5.5). Typically a `{ \"op\": \"skolem\", \"label\": <tag>, \"args\": [<component>…] }` node; the components are canonicalized (a symmetric relation sorts its components, e.g. an undirected edge (min(u,v), max(u,v)); a directed one preserves order) so the same member is named identically across bindings (§5.7). Dense integer ids for the array backend then come from a `{ \"op\": \"rank\" }` over the resulting set. Floats are forbidden in keys (§5.7 / §A.5) — keys are integer or categorical ids."
},
"label": {
"type": "string",
"description": "Optional documentary relation tag for a skolem node (e.g. \"edge\", \"bin\", \"pair\"). Does NOT affect the emitted key; the key components are the node's args."
},
"arg": {
"type": "string",
"description": "For the arg-witness reducers `argmin` / `argmax` (RFC semiring-faq-unified-ir §5.7 rule 6): names the contracted `ranges` index symbol whose value (a 1-based generator id) is RETURNED at the optimum. The op reduces its `expr` body (a declarative scalar FAQ, e.g. a squared-distance metric) over the inner `ranges` candidate domain — optionally pruned by a bin-Skolem `join` / `filter` — and emits the witnessing INDEX rather than the reduced value: `assign[i] = argmin_g dist(point_i, gen_g)`, the nearest-generator assignment. NET-NEW because the closed semiring registry (§5.1) returns values and the value-invention primitives distinct/skolem/rank (§5.5) return sets — neither returns the arg. Materialized at build time as an integer per-element buffer (CONST/DISCRETE cadence, like the §A.8 bin-Skolem `:map` buffers; a CONTINUOUS arg-witness is rejected by §5.7 guard 2). The NORMATIVE tie-break is the SMALLEST arg (smallest generator id): equal `expr` values resolve to the lower index, making the buffer byte-identical across bindings (§5.7). REQUIRED on `argmin` / `argmax`; ignored on any other op. An empty candidate set is an error (no index witnesses the optimum)."
},
"manifold": {
"type": "string",
"description": "For the `intersect_polygon` and `polygon_intersection_area` geometry-kernel leaf ops (RFC semiring-faq-unified-ir §8.1 / Appendix B; CONFORMANCE_SPEC.md §5.8.4): the geometry interpretation under which the two operand polygons are clipped, and the part of the op's contract that makes its tolerance-based conformance comparable. \"planar\": Cartesian/flat clipping (Sutherland–Hodgman / Foster–Hormann) — straight edges in the coordinate plane; wrong at the poles and across the antimeridian, valid only for a small projected patch. \"spherical\": great-circle edges on the unit sphere (the ConservativeRegridding.jl / GeometryOps.jl / S2 default for lon-lat earth meshes) — the correct model for global regridding. \"geodesic\": ellipsoidal-geodesic edges. Great-circle-edge assumption: under \"spherical\"/\"geodesic\" every edge — including a lon-lat edge running along a parallel, which is a small circle, not a great circle — is modelled as a great-circle geodesic, so a coarse polar cell carries a real area error (~4% for a 30° cell next to the pole, growing with the square of the cell's longitude width; RFC §B.4 / §5.8.4). The per-binding kernels offer an opt-in densification of parallel edges into short great-circle segments (`densify_parallel_edges`) to reduce it; it is off by default, so default clip behaviour is unchanged. REQUIRED on every `intersect_polygon` / `polygon_intersection_area` node (the op carries no default — the manifold must be declared, never inferred). Two bindings' clip results may be compared ONLY under the same declared manifold; the flag itself is matched EXACTLY across bindings (it is a discrete label, not a tolerance-based quantity). Meaningful only for `intersect_polygon` and `polygon_intersection_area`; ignored on any other op. TEMPLATE PARAMETERIZATION (esm-spec §9.6.1 / §9.6.3 constraint 5): inside an `expression_templates` entry's `body`, this field MAY carry a declared template-parameter name — a bare string outside the closed set — as a scalar-field substitution site, so the schema admits any string here. The closed set {planar, spherical, geodesic} is enforced on the EXPANDED form per §9.6.4: bindings MUST reject, at post-expansion validation, any `intersect_polygon` / `polygon_intersection_area` node whose `manifold` is not a member of the closed set.",
"anyOf": [
{
"enum": [
"planar",
"spherical",
"geodesic"
]
},
{
"type": "string"
}
]
},
"regions": {
"type": "array",
"description": "For makearray: list of sub-region boxes of the output array. Each region is an array of [start, stop] pairs, one per output dimension. The nth region is filled with the nth entry of values. Overlapping regions are permitted; later regions overwrite earlier ones. Bound pairs MAY be metaparameter expressions folded to concrete integers at load (esm-spec §9.7.6). Mirrors SymbolicUtils.ArrayMaker.regions.",
"items": {
"type": "array",
"items": {
"type": "array",
"items": {
"$ref": "#/$defs/MetaparameterExpression"
},
"minItems": 2,
"maxItems": 2
},
"minItems": 1
}
},
"values": {
"type": "array",
"description": "For makearray: list of expressions, one per entry in regions. Each value may be a scalar expression (broadcast across the region) or an array-valued expression whose shape matches the region (excluding singleton dimensions). Mirrors SymbolicUtils.ArrayMaker.values.",
"items": {
"$ref": "#/$defs/Expression"
}
},
"shape": {
"type": "array",
"description": "For reshape: the target shape. Each entry is either an integer (a concrete length) or a string (a symbolic dimension reference).",
"items": {
"oneOf": [
{
"type": "integer"
},
{
"type": "string"
}
]
},
"minItems": 1
},
"perm": {
"type": "array",
"description": "For transpose: optional axis permutation. A list of 0-based axis indices giving the new order. If omitted, the matrix-transpose convention is used (reverse axes).",
"items": {
"type": "integer",
"minimum": 0
}
},
"axis": {
"type": "integer",
"description": "For concat: the 0-based axis along which to concatenate the operand arrays. All operands must have identical shape on every other axis.",
"minimum": 0
},
"fn": {
"type": "string",
"description": "For broadcast: the name of the scalar operator to apply element-wise to the operands in args (esm-spec.md §4.3.4). `{op: 'broadcast', fn: F, args: A}` means exactly what `{op: F, args: A}` means, applied element-wise — so a ONE-operand broadcast applies `fn` UNARILY (`broadcast(fn:'-',[x])` is `-x`), and MUST NOT be treated as the identity on its operand. The value MUST be an ExpressionNode op name drawn from the closed SCALAR subset — the pointwise ops: arithmetic (`+ - * / ^ neg`), elementary functions (`exp log ln log10 sqrt abs sign floor ceil sin cos tan asin acos atan sinh cosh tanh asinh acosh atanh atan2 min max`), comparisons (`== != < <= > >=`), logical connectives (`and or not`), and `ifelse`. It may NOT name a non-pointwise op (`faq makearray index broadcast reshape transpose concat fn D ic Pre const true enum table_lookup apply_expression_template skolem rank distinct argmin argmax intersect_polygon polygon_intersection_area`), and `args.length` MUST satisfy the named operator's §4.2 arity. Bindings MUST reject a violation — including an absent `fn`, for which there is no default — with diagnostic 'invalid_broadcast_fn'; loading MUST fail. This is a VALUE constraint the schema deliberately does not enum-enforce, for the same reason `op` and the closed-registry `name` are not enum-enforced: the admissible set is fixed by the file's declared `esm` version, and the check must also cover arity, which a schema `enum` cannot express."
},
"name": {
"type": "string",
"description": "For fn: the dotted module path of a function in the closed function registry (esm-spec.md §9.2). The set of valid names is fixed by the spec version; bindings MUST reject unknown names with diagnostic 'unknown_closed_function'. v0.3.0 set: datetime.year, datetime.month, datetime.day, datetime.hour, datetime.minute, datetime.second, datetime.day_of_year, datetime.julian_day, datetime.is_leap_year, interp.searchsorted, interp.linear, interp.bilinear. For apply_expression_template: the id of an `expression_templates` entry declared in the same component (esm-spec.md §9.6 / docs/rfcs/ast-expression-templates.md). Bindings MUST reject references to undeclared template names at file-load time with diagnostic 'apply_expression_template_unknown_template'."
},
"value": {
"description": "For const: the inline literal value carried by this expression node (any JSON number, integer, or nested array thereof; `args` MUST be empty). For the 'bc' op with kind 'constant'/'dirichlet': the boundary value — a number, a parameter/variable-reference string, or an Expression AST node."
},
"units": {
"type": "string",
"description": "For const only: the declared units of the constant's `value`, resolved against the esm-spec §4.8.1 registry with the §4.8.2 grammar exactly as a variable's `units` are. A unit-bearing constant has that dimension and exact scale in dimensional analysis (esm-spec §4.8.5); a `const` without `units`, like a bare numeric literal, stays undeterminable. The numeric value is never checked against the units. Legal on no other op. Arrives at esm 1.2.0 (`const_units_version_too_old`)."
},
"table": {
"type": "string",
"description": "For table_lookup: the id of the function_tables entry to evaluate. Bindings MUST reject references to undeclared tables at file-load time with diagnostic 'table_lookup_unknown_table'."
},
"axes": {
"type": "object",
"description": "For table_lookup: a map from axis name (matching one of the referenced table's `axes[].name` entries) to the scalar input expression supplying that coordinate at evaluation time. Every axis declared on the table MUST appear as a key; extra keys are rejected with 'table_lookup_axis_name_mismatch'. `args` MUST be empty for a table_lookup node — the per-axis expressions live here.",
"additionalProperties": {
"$ref": "#/$defs/Expression"
}
},
"output": {
"description": "For table_lookup: which output of a multi-output table to return. Either a non-negative integer (0-based index into the leading data dimension) or a string (an entry in the table's `outputs` array). Single-output tables MAY omit this field (defaults to 0). Out-of-range or unknown-name selectors are rejected with 'table_lookup_output_out_of_range'.",
"oneOf": [
{
"type": "integer",
"minimum": 0
},
{
"type": "string"
}
]
},
"bindings": {
"type": "object",
"description": "For apply_expression_template: a map from each parameter name declared by the referenced template to the Expression bound to that parameter. Every entry of the template's `params` MUST appear as a key; extra keys are rejected at load time with diagnostic 'apply_expression_template_bindings_mismatch'. Values may be numeric literals, variable name references (strings), or arbitrary Expression ASTs (full subtrees). `args` MUST be empty for an apply_expression_template node — the parameter values live here.",
"additionalProperties": {
"$ref": "#/$defs/Expression"
}
}
},
"additionalProperties": false,
"allOf": [
{
"if": {
"properties": {
"op": {
"enum": [
"faq",
"aggregate"
]
}
},
"required": [
"op"
]
},
"then": {
"required": [
"output_idx",
"expr"
]
}
},
{
"if": {
"properties": {
"op": {
"const": "makearray"
}
},
"required": [
"op"
]
},
"then": {
"required": [
"regions",
"values"
]
}
},
{
"if": {
"properties": {
"op": {
"const": "broadcast"
}
},
"required": [
"op"
]
},
"then": {
"required": [
"fn"
]
}
},
{
"if": {
"properties": {
"op": {
"const": "reshape"
}
},
"required": [
"op"
]
},
"then": {
"required": [
"shape"
]
}
},
{
"if": {
"properties": {
"op": {
"const": "concat"
}
},
"required": [
"op"
]
},
"then": {
"required": [
"axis"
]
}
},
{
"if": {
"properties": {
"op": {
"const": "fn"
}
},
"required": [
"op"
]
},
"then": {
"required": [
"name"
]
}
},
{
"if": {
"properties": {
"op": {
"const": "const"
}
},
"required": [
"op"
]
},
"then": {
"required": [
"value"
]
}
},
{
"if": {
"properties": {
"op": {
"const": "enum"
}
},
"required": [
"op"
]
},
"then": {
"properties": {
"args": {
"type": "array",
"minItems": 2,
"maxItems": 2,
"items": {
"type": "string"
}
}
}
}
},
{
"if": {
"properties": {
"op": {
"const": "table_lookup"
}
},
"required": [
"op"
]
},
"then": {
"required": [
"table",
"axes"
],
"properties": {
"args": {
"type": "array",
"maxItems": 0
}
}
}
},
{
"if": {
"properties": {
"op": {
"const": "apply_expression_template"
}
},
"required": [
"op"
]
},
"then": {
"required": [
"name",
"bindings"
],
"properties": {
"args": {
"type": "array",
"maxItems": 0
}
}
}
},
{
"if": {
"properties": {
"op": {
"const": "integral"
}
},
"required": [
"op"
]
},
"then": {
"required": [
"var",
"lower",
"upper"
],
"properties": {
"args": {
"type": "array",
"minItems": 1,
"maxItems": 1
}
}
}
},
{
"$comment": "esm-spec §4.2 \"Arity of `D`\" / §9.6.8. The STRUCTURAL time derivative is strictly unary: it is evaluable-core and is consumed by system assembly, which has no place for a second operand. An absent `wrt` means `t`, so this clause fires on {op:D} with no `wrt` too (the `properties` subschema is vacuously satisfied). A REWRITE-TARGET `D` (any `wrt` other than \"t\", including a parameter-valued `wrt` inside a rewrite-rule `match`) is deliberately NOT constrained here: it may carry an unbounded number of trailing auxiliary operands — per-face boundary/halo data that a discretization rule binds and consumes — which have no evaluator semantics because a spatial `D` is never evaluated directly.",
"if": {
"properties": {
"op": {
"const": "D"
},
"wrt": {
"const": "t"
}
},
"required": [
"op"
]
},
"then": {
"properties": {
"args": {
"type": "array",
"minItems": 1,
"maxItems": 1
}
}
}
},
{
"if": {
"properties": {
"op": {
"enum": [
"intersect_polygon",
"polygon_intersection_area"
]
}
},
"required": [
"op"
]
},
"then": {
"required": [
"manifold"
],
"properties": {
"args": {
"type": "array",
"minItems": 2,
"maxItems": 2
}
}
}
},
{
"if": {
"required": [
"units"
]
},
"then": {
"properties": {
"op": {
"const": "const"
}
}
}
}
]
},
"Equation": {
"type": "object",
"description": "An equation: lhs = rhs (or lhs ~ rhs in MTK notation).",
"required": [
"lhs",
"rhs"
],
"additionalProperties": false,
"properties": {
"lhs": {
"$ref": "#/$defs/Expression"
},
"rhs": {
"$ref": "#/$defs/Expression"
},
"_comment": {
"type": "string"
}
}
},
"AffectEquation": {
"type": "object",
"description": "An affect equation in an event: lhs is the target variable (string), rhs is an expression.",
"required": [
"lhs",
"rhs"
],
"additionalProperties": false,
"properties": {
"lhs": {
"type": "string",
"description": "Target variable name (value after the event)."
},
"rhs": {
"$ref": "#/$defs/Expression",
"description": "Expression for the new value. Use Pre(var) to reference pre-event values."
}
}
},
"ContinuousEvent": {
"type": "object",
"description": "Fires when a condition expression crosses zero (root-finding). Maps to MTK SymbolicContinuousCallback. An event may affect UNKNOWNS ONLY; a parameter that changes on a zero crossing declares `update: {kind: \"crossing\", …}` on itself instead.",
"required": [
"conditions",
"affects"
],
"additionalProperties": false,
"properties": {
"name": {
"type": "string",
"description": "Human-readable identifier."
},
"conditions": {
"type": "array",
"description": "Expressions that trigger the event when they cross zero.",
"items": {
"$ref": "#/$defs/Expression"
},
"minItems": 1
},
"affects": {
"type": "array",
"description": "Affect equations applied on positive-going zero crossings (or both directions if affect_neg is absent). Empty array for pure detection. Every LHS MUST name an unknown (`event_affects_parameter` otherwise).",
"items": {
"$ref": "#/$defs/AffectEquation"
}
},
"affect_neg": {
"description": "Separate affects for negative-going zero crossings. If null or absent, affects is used for both directions.",
"oneOf": [
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/AffectEquation"
}
}
]
},
"root_find": {
"type": "string",
"description": "Root-finding direction.",
"enum": [
"left",
"right"
],
"default": "left"
},
"reinitialize": {
"type": "boolean",
"description": "Whether to reinitialize the system after the event.",
"default": false
},
"description": {
"type": "string"
}
}
},
"DiscreteEventTrigger": {
"description": "Trigger specification for a discrete event.",
"oneOf": [
{
"type": "object",
"description": "Fires when the boolean expression is true at the end of a timestep.",
"required": [
"type",
"expression"
],
"additionalProperties": false,
"properties": {
"type": {
"const": "condition"
},
"expression": {
"$ref": "#/$defs/Expression"
}
}
},
{
"type": "object",
"description": "Fires every interval time units.",
"required": [
"type",
"interval"
],
"additionalProperties": false,
"properties": {
"type": {
"const": "periodic"
},
"interval": {
"type": "number",
"exclusiveMinimum": 0,
"description": "Interval in simulation time units."
},
"initial_offset": {
"type": "number",
"description": "Offset from t=0 for the first firing.",
"default": 0
}
}
},
{
"type": "object",
"description": "Fires at each specified time.",
"required": [
"type",
"times"
],
"additionalProperties": false,
"properties": {
"type": {
"const": "preset_times"
},
"times": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 1,
"description": "Array of simulation times at which to fire."
}
}
}
]
},
"DiscreteEvent": {
"type": "object",
"description": "Fires when a boolean condition is true at end of a timestep, or at preset/periodic times. Maps to MTK SymbolicDiscreteCallback. An event may affect UNKNOWNS ONLY: from 1.0.0 a parameter carries its own `update` block, so there is no `discrete_parameters` list and no `functional_affect` here — a handler only ever wrote parameters, and now lives on the parameter it writes.",
"required": [
"trigger",
"affects"
],
"additionalProperties": false,
"properties": {
"name": {
"type": "string",
"description": "Human-readable identifier."
},
"trigger": {
"$ref": "#/$defs/DiscreteEventTrigger"
},
"affects": {
"type": "array",
"description": "Affect equations. Every LHS MUST name an unknown (`event_affects_parameter` otherwise).",
"items": {
"$ref": "#/$defs/AffectEquation"
}
},
"reinitialize": {
"type": "boolean",
"description": "Whether to reinitialize the system after the event."
},
"description": {
"type": "string"
}
}
},
"Distribution": {
"description": "A parameter's value drawn from a probability distribution rather than fixed. The closed set is `normal`, `lognormal`, and `uniform` (esm-spec §9.1's closed-registry principle applies here too: bindings implement exactly these and reject anything else). WHEN it is drawn is decided by the parameter's `update`, and that is the whole difference between the two uses of this field: with NO update the value is sampled ONCE at setup and held for the run (the uncertainty-quantification / ensemble case), while `update.kind: \"wiener\"` resamples it every step with √dt increment scaling (the stochastic-process case that promotes the model to an SDE). A distribution is univariate when its location parameter is a number and multivariate when it is an array, in which case the parameter's `shape` MUST agree.",
"oneOf": [
{
"type": "object",
"description": "Gaussian. Give `std` for independent components or `cov` for a full covariance matrix — exactly one of the two, never both.",
"required": [
"kind",
"mean"
],
"additionalProperties": false,
"properties": {
"kind": {
"const": "normal"
},
"mean": {
"oneOf": [
{
"type": "number"
},
{
"type": "array",
"items": {
"type": "number"
},
"minItems": 1
}
],
"description": "Mean. A number for a scalar parameter; an array for a vector-valued one, whose length MUST match the parameter's shape."
},
"std": {
"oneOf": [
{
"type": "number",
"exclusiveMinimum": 0
},
{
"type": "array",
"items": {
"type": "number",
"exclusiveMinimum": 0
},
"minItems": 1
}
],
"description": "Standard deviation of INDEPENDENT components — a number, or one entry per component. Mutually exclusive with `cov`."
},
"cov": {
"$ref": "#/$defs/CovarianceMatrix"
}
},
"oneOf": [
{
"required": [
"std"
]
},
{
"required": [
"cov"
]
}
]
},
{
"type": "object",
"description": "Log-normal: the natural logarithm of the value is normally distributed with mean `mu` and spread `sigma` / `cov`. Both spread forms are on the LOG scale.",
"required": [
"kind",
"mu"
],
"additionalProperties": false,
"properties": {
"kind": {
"const": "lognormal"
},
"mu": {
"oneOf": [
{
"type": "number"
},
{
"type": "array",
"items": {
"type": "number"
},
"minItems": 1
}
],
"description": "Mean of the underlying normal (log scale)."
},
"sigma": {
"oneOf": [
{
"type": "number",
"exclusiveMinimum": 0
},
{
"type": "array",
"items": {
"type": "number",
"exclusiveMinimum": 0
},
"minItems": 1
}
],
"description": "Standard deviation of the underlying normal (log scale), for independent components. Mutually exclusive with `cov`."
},
"cov": {
"$ref": "#/$defs/CovarianceMatrix"
}
},
"oneOf": [
{
"required": [
"sigma"
]
},
{
"required": [
"cov"
]
}
]
},
{
"type": "object",
"description": "Uniform on [low, high]. Components are independent by construction, so there is no covariance form; `low` and `high` are numbers for a scalar parameter or equal-length arrays for a vector-valued one, and every `low` MUST be strictly below its `high`.",
"required": [
"kind",
"low",
"high"
],
"additionalProperties": false,
"properties": {
"kind": {
"const": "uniform"
},
"low": {
"oneOf": [
{
"type": "number"
},
{
"type": "array",
"items": {
"type": "number"
},
"minItems": 1
}
]
},
"high": {
"oneOf": [
{
"type": "number"
},
{
"type": "array",
"items": {
"type": "number"
},
"minItems": 1
}
]
}
}
}
]
},
"CovarianceMatrix": {
"type": "array",
"description": "Symmetric positive-semidefinite covariance matrix in row-major order: entry [i][j] is the covariance of components i and j. MUST be square, and its order MUST equal the length of the accompanying `mean` / `mu` vector and of the parameter's declared `shape`. A binding MUST reject a non-square, non-symmetric, or non-positive-semidefinite matrix at load with `distribution_covariance_invalid` rather than silently repairing it. This is how the format encodes correlated noise: one vector-valued parameter with a `cov`, instead of the opaque correlation-group tags the 0.x schema used and never gave a matrix for.",
"minItems": 1,
"items": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 1
}
},
"ParameterUpdate": {
"description": "Declares WHEN a parameter refreshes and WHAT it refreshes from. A parameter with no `update` is a constant (or, with a `distribution`, is sampled once at setup). Six kinds. `wiener` is a driving stochastic process and takes no value form — it resamples the parameter's own `distribution`. The other five each take EXACTLY ONE value form: an `expression`, a `from` binding to a data source, or a registered `handler`. Together they subsume three constructs the 0.x format kept apart: the `brownian` variable type (now `wiener`), the `discrete` type with its `RefreshTrigger` (now `schedule` / `data` / `remesh`), and the `discrete_parameters` event lists with their `functional_affect` (now `condition` / `crossing`). This is also the sole seed of the DISCRETE cadence class in the dependency-partition pass (RFC semiring-faq-unified-ir §6.1): without it such inputs would be mis-seeded as CONST (never refresh) or CONTINUOUS (recompute every step).",
"oneOf": [
{
"type": "object",
"description": "wiener: a driving Wiener (Brownian) process. The parameter's `distribution` is resampled every step with √dt increment scaling, which is why such a parameter's units carry a 1/s^0.5-style intensity rather than the units of the quantity it drives (esm-spec §4.8.4). The presence of ANY wiener-updated parameter promotes the enclosing model from an ODE system to an SDE system. Correlated noise is one vector-valued parameter whose `distribution` carries a `cov`; there is no separate correlation-group tag and no value form to give, because the distribution IS the value.",
"required": [
"kind"
],
"additionalProperties": false,
"properties": {
"kind": {
"const": "wiener"
}
}
},
{
"type": "object",
"description": "schedule: time-driven refresh on a tstops schedule (the MTK PresetTimeCallback / tstops analogue). Refreshes at the listed preset `times` and/or on a periodic `interval`; at least one of the two MUST be present.",
"required": [
"kind"
],
"additionalProperties": false,
"properties": {
"kind": {
"const": "schedule"
},
"times": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 1,
"description": "Explicit simulation times (the tstops) at which the parameter refreshes."
},
"interval": {
"type": "number",
"exclusiveMinimum": 0,
"description": "Periodic refresh interval in simulation time units."
},
"initial_offset": {
"type": "number",
"default": 0,
"description": "Offset from t=0 for the first periodic refresh. Ignored when `interval` is absent."
},
"expression": {
"$ref": "#/$defs/Expression",
"description": "The parameter's new value, computed symbolically when the update fires."
},
"from": {
"$ref": "#/$defs/DataSourceBinding",
"description": "The parameter's new value, read from the named data source."
},
"handler": {
"$ref": "#/$defs/FunctionalUpdate",
"description": "The parameter's new value, computed by a registered handler — the escape hatch for behavior no expression can state (control logic, external calls, table interpolation)."
}
},
"allOf": [
{
"anyOf": [
{
"required": [
"times"
]
},
{
"required": [
"interval"
]
}
]
},
{
"oneOf": [
{
"required": [
"expression"
]
},
{
"required": [
"from"
]
},
{
"required": [
"handler"
]
}
]
}
]
},
{
"type": "object",
"description": "condition: refresh at the end of any timestep at which the boolean `when` expression is true — the 0.x discrete-event `condition` trigger, relocated onto the parameter it writes.",
"required": [
"kind",
"when"
],
"additionalProperties": false,
"properties": {
"kind": {
"const": "condition"
},
"when": {
"$ref": "#/$defs/Expression",
"description": "Boolean expression tested at the end of each timestep."
},
"expression": {
"$ref": "#/$defs/Expression",
"description": "The parameter's new value, computed symbolically when the update fires."
},
"from": {
"$ref": "#/$defs/DataSourceBinding",
"description": "The parameter's new value, read from the named data source."
},
"handler": {
"$ref": "#/$defs/FunctionalUpdate",
"description": "The parameter's new value, computed by a registered handler — the escape hatch for behavior no expression can state (control logic, external calls, table interpolation)."
}
},
"oneOf": [
{
"required": [
"expression"
]
},
{
"required": [
"from"
]
},
{
"required": [
"handler"
]
}
]
},
{
"type": "object",
"description": "crossing: refresh when the `when` expression crosses zero, located by root-finding — the 0.x continuous-event trigger, relocated onto the parameter it writes. Use this rather than `condition` when the exact crossing time matters.",
"required": [
"kind",
"when"
],
"additionalProperties": false,
"properties": {
"kind": {
"const": "crossing"
},
"when": {
"$ref": "#/$defs/Expression",
"description": "Expression whose zero crossing triggers the refresh."
},
"direction": {
"type": "string",
"enum": [
"up",
"down",
"any"
],
"default": "any",
"description": "Which crossings count: positive-going (`up`), negative-going (`down`), or both (`any`, the default)."
},
"expression": {
"$ref": "#/$defs/Expression",
"description": "The parameter's new value, computed symbolically when the update fires."
},
"from": {
"$ref": "#/$defs/DataSourceBinding",
"description": "The parameter's new value, read from the named data source."
},
"handler": {
"$ref": "#/$defs/FunctionalUpdate",
"description": "The parameter's new value, computed by a registered handler — the escape hatch for behavior no expression can state (control logic, external calls, table interpolation)."
}
},
"oneOf": [
{
"required": [
"expression"
]
},
{
"required": [
"from"
]
},
{
"required": [
"handler"
]
}
]
},
{
"type": "object",
"description": "data: refresh when the named data source advances to a new record — the next met or boundary-condition slice, the next emissions month. This is how external data enters a model in 1.0.0, replacing the `data_loaders` component and its coupling edge: the parameter IS the loaded field. Ordinarily paired with a `from` binding; an `expression` or `handler` instead refreshes a DERIVED quantity on the same cadence as the source it depends on.",
"required": [
"kind",
"source"
],
"additionalProperties": false,
"properties": {
"kind": {
"const": "data"
},
"source": {
"type": "string",
"description": "Key of the `data_sources` entry whose record advance drives this refresh. MUST resolve (`data_source_undefined`)."
},
"expression": {
"$ref": "#/$defs/Expression",
"description": "The parameter's new value, computed symbolically when the update fires."
},
"from": {
"$ref": "#/$defs/DataSourceBinding",
"description": "The parameter's new value, read from the named data source."
},
"handler": {
"$ref": "#/$defs/FunctionalUpdate",
"description": "The parameter's new value, computed by a registered handler — the escape hatch for behavior no expression can state (control logic, external calls, table interpolation)."
}
},
"oneOf": [
{
"required": [
"expression"
]
},
{
"required": [
"from"
]
},
{
"required": [
"handler"
]
}
]
},
{
"type": "object",
"description": "remesh: refresh on a mesh-topology change (AMR refinement, or a moving / reloaded mesh). The refreshed quantity is typically mesh topology or coefficients derived from it.",
"required": [
"kind"
],
"additionalProperties": false,
"properties": {
"kind": {
"const": "remesh"
},
"hook": {
"type": "string",
"description": "Optional name of the remesh hook driving the refresh. Absent ⇒ refresh on any remesh event."
},
"expression": {
"$ref": "#/$defs/Expression",
"description": "The parameter's new value, computed symbolically when the update fires."
},
"from": {
"$ref": "#/$defs/DataSourceBinding",
"description": "The parameter's new value, read from the named data source."
},
"handler": {
"$ref": "#/$defs/FunctionalUpdate",
"description": "The parameter's new value, computed by a registered handler — the escape hatch for behavior no expression can state (control logic, external calls, table interpolation)."
}
},
"oneOf": [
{
"required": [
"expression"
]
},
{
"required": [
"from"
]
},
{
"required": [
"handler"
]
}
]
}
]
},
"ParameterUpdateSpec": {
"description": "A parameter's update behavior: EITHER a single rule, OR an ordered array of two or more rules. The array form exists because collapsing parameter mutation onto the parameter must not cost expressiveness that events had: before 1.0.0 any number of events could write one parameter, and a counter incremented on two different schedules, a mode switch driven by two conditions, and a continuous event's `affects` / `affect_neg` pair are each ONE parameter with several rules. Splitting them into several parameters would change the model, because the equations read one name. Rules are independent: at any point where more than one rule's trigger fires, they apply in DECLARATION ORDER, so a later rule's `expression` sees the earlier rule's result and `Pre` still means the value before this firing as a whole. A single rule MUST be written as the object form — a one-element array is invalid — so the representation of any given update set is unique and the round-trip is stable. `wiener` is admissible only as the object form: a driving noise process is the parameter's whole value, so combining it with scheduled writes is incoherent.",
"oneOf": [
{
"$ref": "#/$defs/ParameterUpdate"
},
{
"type": "array",
"minItems": 2,
"items": {
"allOf": [
{
"$ref": "#/$defs/ParameterUpdate"
},
{
"not": {
"properties": {
"kind": {
"const": "wiener"
}
},
"required": [
"kind"
]
}
}
]
}
}
]
},
"FunctionalUpdate": {
"type": "object",
"description": "A registered handler that computes this parameter's new value when the update fires. This is the 0.x event `functional_affect` relocated: a handler's only write channel was `modified_params`, so it now lives ON the parameter it writes and needs no write list at all. Handlers stay deliberately out of scope for the §9 closed function registry — they mutate simulator state at update time, while §9 entries are pure expression-embedded callables. `handler_id` is the sole remaining registration mechanism in the format.",
"required": [
"handler_id"
],
"additionalProperties": false,
"properties": {
"handler_id": {
"type": "string",
"description": "Registered identifier for the handler implementation."
},
"read_vars": {
"type": "array",
"items": {
"type": "string"
},
"description": "Unknowns read by the handler. Absent means none."
},
"read_params": {
"type": "array",
"items": {
"type": "string"
},
"description": "Parameters read by the handler. Absent means none."
},
"config": {
"type": "object",
"description": "Handler-specific configuration, passed through verbatim.",
"additionalProperties": true
}
}
},
"DataSourceBinding": {
"type": "object",
"description": "Binds a parameter to one variable of a `data_sources` entry. This is the 0.x `DataLoaderVariable` minus `units`: the units are the parameter's own, declared once on the parameter instead of twice. `select` here overrides the source-level default for this parameter only, which is how a full-grid field and a prefix of it are both read from one `file_variable` without either being sliced by the consumer.",
"required": [
"file_variable"
],
"additionalProperties": false,
"properties": {
"file_variable": {
"type": "string",
"description": "Name of the variable in the source file supplying this parameter's values."
},
"unit_conversion": {
"$ref": "#/$defs/Expression",
"description": "Multiplicative factor applied to the raw file values to reach the parameter's declared `units` — a plain number or a full Expression AST (§4), as the 0.x loader-variable form allowed. `Expression` already admits the bare number, so this is a single `$ref`: spelling it `oneOf: [number, Expression]` (which is what 0.x did) is unsatisfiable for every plain factor, since a number matches BOTH branches. Scales a number that is already a number — contrast `codes`, which decodes a text label into one. As an Expression position it is subject to reference integrity (esm-spec §4.9.5): its free names must resolve."
},
"codes": {
"$ref": "#/$defs/DataSourceCodes"
},
"select": {
"$ref": "#/$defs/DataSourceSelect"
},
"description": {
"type": "string"
},
"reference": {
"$ref": "#/$defs/Reference"
}
}
},
"NumericArrayLiteral": {
"type": "array",
"description": "A row-major nested JSON array of numbers carrying a SHAPED variable's inline data (esm-spec §6.3, §6.6.2). Every axis is a JSON array and every leaf a number; the nesting depth and the per-axis lengths MUST match the variable's declared `shape` after metaparameter folding, and a mismatch is a load-time error — the same convention `from_file` data already follows (§6.6.5 convention 3). A SCALAR in the same position keeps its broadcast meaning (one value applied to every element).",
"items": {
"oneOf": [
{
"type": "number"
},
{
"$ref": "#/$defs/NumericArrayLiteral"
}
]
}
},
"ModelVariable": {
"type": "object",
"description": "A variable in a model — either an `unknown` the solver solves for, or a `parameter` supplied to it. There is no third kind. Everything the solver additionally needs to know is DERIVED: whether an unknown is an ODE state, an observed quantity, or an algebraic one follows from the EQUATIONS, and whether a parameter is Brownian, discrete, sampled, or constant follows from its `distribution` and `update` (esm-spec §6.3.1).",
"required": [
"type"
],
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"enum": [
"unknown",
"parameter"
],
"description": "unknown = a quantity the solver solves for; its behavior is stated by the model's `equations` and NOWHERE else. parameter = a quantity supplied to the solver, whose value is `default` or a `distribution`, optionally refreshed by an `update`. A checker MUST NOT infer an unknown's role from anything but the equations: an unknown under `D(·, t)` on some equation LHS is an ODE state, one with a bare-variable LHS is observed (eliminable), and one constrained only implicitly (`H*H*SO4 ~ Ksp`) is algebraic."
},
"units": {
"type": "string"
},
"default": {
"oneOf": [
{
"type": "number"
},
{
"$ref": "#/$defs/NumericArrayLiteral"
}
],
"description": "For an unknown, its initial value at t=0. For a parameter, its constant value — mutually exclusive with `distribution`, which draws the value instead. A SHAPED variable (non-empty `shape`) may instead carry a row-major nested JSON array whose nesting matches the declared shape after metaparameter folding; a mismatch is a load-time error. A scalar on a shaped variable keeps its broadcast meaning — the one value applies to every element (esm-spec §6.3)."
},
"default_units": {
"type": "string",
"description": "Units of the default value, if different from the declared units field. When present, validators flag a unit_inconsistency error if these do not match the declared units (including dimensionally incompatible cases like K vs kg, and same-dimension mismatches like K vs degC). Default is the same as `units`."
},
"element_type": {
"type": "string",
"enum": [
"Float32",
"Float64"
],
"description": "Floating-point precision of THIS variable and of the arithmetic over it, overriding the document-wide `domain.element_type` (esm-spec §11.3.1). It exists for the key/quantity split one document-wide precision cannot express: a relational model whose floating-point QUANTITIES are binary32 still has join keys and integer identifiers binary32 cannot represent (a ten-digit category code is ~2.26e9, 135x binary32's exact-integer limit of 2^24), so the keys declare `Float64` while the quantities follow the document. Precision propagates from the leaves: an operator evaluates at its operands' precision, a numeric literal adopts its context's, and an operator whose operands carry DIFFERENT precisions is an error naming both variables — never a silent widening. Omitted means the document's `domain.element_type`."
},
"description": {
"type": "string"
},
"shape": {
"type": "array",
"items": {
"type": "string"
},
"description": "Arrayed-variable shape: ordered list of index-set names drawn from the document-scoped `index_sets` registry. Omitted or null indicates a scalar. REQUIRED for a parameter whose `update` is `schedule`, `data`, or `remesh` — such a parameter is a buffer whose extent is fixed at setup and refilled on a discrete cadence, so its extent must be known ahead of time (RFC semiring-faq-unified-ir §6.1); an empty array is a valid (scalar) shape."
},
"location": {
"type": "string",
"description": "Optional free-form placement tag for a staggered quantity (e.g., \"cell_center\", \"edge_normal\", \"x_face\", \"vertex\"). Advisory metadata only; the index set a quantity lives on is given by `shape`. Omitted indicates no explicit placement."
},
"distribution": {
"$ref": "#/$defs/Distribution",
"description": "Parameter-only: draw this parameter's value from a distribution instead of fixing it at `default`. Mutually exclusive with `default`. With no `update` it is drawn ONCE at setup (uncertainty quantification / ensembles); with `update.kind: \"wiener\"` it is redrawn every step with √dt scaling (a stochastic process, which makes the model an SDE)."
},
"update": {
"$ref": "#/$defs/ParameterUpdateSpec",
"description": "Parameter-only: when this parameter refreshes and what it refreshes from. Absent means it never changes after setup."
}
},
"allOf": [
{
"if": {
"properties": {
"type": {
"const": "parameter"
}
},
"required": [
"type"
]
},
"else": {
"not": {
"anyOf": [
{
"required": [
"distribution"
]
},
{
"required": [
"update"
]
}
]
}
}
},
{
"if": {
"properties": {
"update": {
"anyOf": [
{
"type": "object",
"properties": {
"kind": {
"const": "wiener"
}
},
"required": [
"kind"
]
},
{
"type": "array",
"contains": {
"properties": {
"kind": {
"const": "wiener"
}
},
"required": [
"kind"
]
}
}
]
}
},
"required": [
"update"
]
},
"then": {
"required": [
"distribution"
]
}
},
{
"if": {
"properties": {
"update": {
"anyOf": [
{
"type": "object",
"properties": {
"kind": {
"enum": [
"schedule",
"data",
"remesh"
]
}
},
"required": [
"kind"
]
},
{
"type": "array",
"contains": {
"properties": {
"kind": {
"enum": [
"schedule",
"data",
"remesh"
]
}
},
"required": [
"kind"
]
}
}
]
}
},
"required": [
"update"
]
},
"then": {
"required": [
"shape"
]
}
},
{
"not": {
"required": [
"default",
"distribution"
]
}
}
]
},
"Model": {
"type": "object",
"description": "An ODE system — a fully specified set of time-dependent equations.",
"required": [
"variables",
"equations"
],
"additionalProperties": false,
"properties": {
"reference": {
"$ref": "#/$defs/Reference"
},
"variables": {
"propertyNames": { "$ref": "#/$defs/Identifier" },
"type": "object",
"description": "All variables, keyed by name.",
"additionalProperties": {
"$ref": "#/$defs/ModelVariable"
}
},
"equations": {
"type": "array",
"description": "Array of {lhs, rhs} equation objects.",
"items": {
"$ref": "#/$defs/Equation"
}
},
"initialization_equations": {
"type": "array",
"description": "Equations that hold only at t=0 (not dynamically). Used by models whose initialization requires solving an auxiliary system before time-stepping begins (e.g. aerosol equilibrium, plume rise). Each entry is a {lhs, rhs} equation evaluated/solved at t=0.",
"items": {
"$ref": "#/$defs/Equation"
}
},
"guesses": {
"type": "object",
"description": "Initial-guess seeds for nonlinear solvers during initialization, keyed by variable name. Values are Expression graphs (numbers, strings, or ExpressionNode).",
"additionalProperties": {
"$ref": "#/$defs/Expression"
}
},
"system_kind": {
"type": "string",
"description": "Discriminates the MTK system type this model maps to. Defaults to 'ode' (time-stepping). 'nonlinear' for algebraic-only systems (no time derivative; e.g. aerosol equilibrium, Mogi). 'sde' when any parameter carries a `wiener` update. 'pde' for models whose equations contain a SPATIAL DERIVATIVE -- a `D` whose `wrt` is present and is not 't', or one of the `grad`/`div`/`laplacian` sugar ops. Note this is a property of the EQUATIONS, not of the `domain` block: v0.8.0 removed `Domain.spatial`, so `domain` carries nothing spatial and the older 'spatial domain plus differential operators' wording named a test no binding could perform. From 1.0.0 this field is a DECLARATION of something the equations and parameter updates already determine: bindings expose a `system_kind` classifier that derives it, use the derivation when this field is absent, and report `system_kind_mismatch` when a present field contradicts it. Derivation order is sde, then pde, then nonlinear, then ode (esm-spec 6.3.1): a steady-state PDE has no time derivative and must not fall through to 'nonlinear', while a model that is both stochastic and spatial assembles as an SDE because there is no SPDESystem constructor.",
"enum": [
"ode",
"nonlinear",
"sde",
"pde"
]
},
"discrete_events": {
"type": "array",
"items": {
"$ref": "#/$defs/DiscreteEvent"
}
},
"continuous_events": {
"type": "array",
"items": {
"$ref": "#/$defs/ContinuousEvent"
}
},
"subsystems": {
"propertyNames": { "$ref": "#/$defs/Identifier" },
"type": "object",
"description": "Named child subsystems, keyed by unique identifier. A subsystem is a child model, or a reference to an external file containing exactly one. Enables hierarchical model composition. Variables in subsystems are referenced via dot notation: \"ParentModel.ChildModel.var\". Each subsystem can be defined inline or included by reference via a local file path or URL. A `data_sources` entry is NOT a component and cannot be a subsystem: a model reaches external data through a parameter whose `update` names the source.",
"additionalProperties": {
"oneOf": [
{
"$ref": "#/$defs/Model"
},
{
"$ref": "#/$defs/SubsystemRef"
}
]
}
},
"tolerance": {
"$ref": "#/$defs/Tolerance",
"description": "Model-level default numerical tolerance for tests. Resolution is PER FIELD over four levels (esm-spec 6.6.4): assertion, test, model, then the implementation default (rel = 1e-6, no abs bound). abs and rel each take their value from the innermost level that declares that field, so a test or assertion that declares only one bound does not mask the other from here. An explicit 0 is a declaration ('no bound of this kind'), not an absence, and stops the fallthrough - including the fallthrough to the implementation default, which is why rel: 0 is the only way to ask for an absolute-only comparison."
},
"tests": {
"type": "array",
"description": "Inline validation tests that exercise this model in isolation. Each test specifies initial conditions, parameter overrides, a time span, and scalar assertions at specific (variable, time) points.",
"items": {
"$ref": "#/$defs/Test"
}
},
"analyses": {
"type": "array",
"description": "Inline illustrative analyses of how to run this model. Each analysis specifies initial state, parameters, a time span, an optional parameter sweep, and plot specifications.",
"items": {
"$ref": "#/$defs/Analysis"
}
},
"expression_templates": {
"propertyNames": { "$ref": "#/$defs/Identifier" },
"type": "object",
"description": "Component-scoped in-file Expression-AST templates (v0.4.0; docs/rfcs/ast-expression-templates.md). Each entry names a fixed Expression body with parameter substitution slots; `apply_expression_template` AST nodes elsewhere in this component reference the entry by key with per-parameter bindings. Templates are component-local: declarations here are visible only within this model's expression positions. A body MAY reference other match-less in-scope templates as a statically-checked acyclic DAG — no cycles, no recursion (esm-spec §9.7.3). From esm 0.9.0 the round-trip is Option B (reference-preserving, esm-spec §9.6.4): references survive load and parse-then-emit and denote their expansion (`Expand`); eager (target-bearing) references still expand at load; emit materializes referenced templates into this registry — authored entries first in authored order, then materialized entries in lexicographic UTF-8 name order; keys may be dotted post-rename names. Pre-0.9.0 loaders expanded every reference at load (Option A) and emitted the expanded form.",
"additionalProperties": {
"$ref": "#/$defs/ExpressionTemplate"
}
},
"expression_template_imports": {
"type": "array",
"description": "Ordered imports of template-library files into this component's template scope (esm-spec §9.7.2). Imported templates join the §9.6.3 effective declaration order ahead of local declarations (§9.7.4).",
"items": {
"$ref": "#/$defs/TemplateImport"
}
}
}
},
"SubsystemRef": {
"type": "object",
"description": "A reference to an external ESM file containing a model or reaction system definition. The ref field can be a relative or absolute local file path, or an HTTP/HTTPS URL. Relative paths are resolved relative to the directory of the referencing file.",
"required": [
"ref"
],
"additionalProperties": false,
"properties": {
"ref": {
"type": "string",
"description": "Local file path or URL pointing to an ESM file. The referenced file must contain exactly one top-level model or reaction system (unless `model` / `reaction_system` selects one of several), which is used as the subsystem definition (esm-spec.md §4.7)."
},
"model": {
"type": "string",
"description": "Optional model selector. When the referenced file defines more than one top-level model, names which one to splice in. Omit for single-model files. Lets a multi-model component library (e.g. an ESD regridder file holding several kernels) be referenced by one of its models."
},
"reaction_system": {
"type": "string",
"description": "Optional reaction-system selector. When the referenced file defines more than one top-level reaction system, names which one to splice in. Omit for single-reaction-system files. The reaction-system analogue of `model`, used when a top-level `reaction_systems` entry is a `{ref}` stub (esm-spec.md §4.7)."
},
"bindings": {
"type": "object",
"additionalProperties": {
"$ref": "#/$defs/MetaparameterExpression"
},
"description": "Bindings closing the referenced document's metaparameters (esm-spec §9.7.6 site 3). Each value is a metaparameter expression over the MOUNTING document's metaparameters (an integer literal, or e.g. `NX*NY`), folded to a concrete integer at the mount."
},
"expression_template_imports": {
"type": "array",
"description": "Template-library imports registered into the REFERENCED component's template scope (esm-spec §9.7.10) — assembler-chosen discretization for a mounted PDE component, without editing the leaf file. Same entry shape as §9.7.2; target implicit (this edge mounts one component). Load-time only; consumed by the §9.6.3 fixpoint; does not survive parse→emit.",
"items": {
"$ref": "#/$defs/TemplateImport"
}
},
"index_set_rename": {
"type": "object",
"additionalProperties": {
"type": "string",
"minLength": 1
},
"description": "Mount-edge index-set renaming (esm-spec §4.7 'Mount-edge index-set renaming'; docs/content/rfcs/mount-edge-index-set-renaming.md): a map from an index-set name AS THE RESOLVED MOUNTED DOCUMENT SPELLS IT to the name it takes in the mounting document. `index_sets` is a document-scoped registry, so two mounts that independently use one axis name at different lengths (a 59-layer atmospheric column and a 4-layer soil column both over `lev`) collide with subsystem_index_set_conflict; this field is the §9.7.7 renaming mechanism at a component-mount edge, restricted to index sets because they are the only declaration kind a mount contributes to document scope. Applied as ONE simultaneous substitution AFTER the referenced document resolves completely (its own imports, this edge's `bindings` and injection, its metaparameter close and the §9.6.3 fixpoint) and BEFORE its `index_sets` merge, transitively through every occurrence inside the mounted document — `index_sets` keys and ragged `of` lists, `{\"from\": …}` ranges, the `wrt`/`dim`/`var` axis scalars and bare-axis-name `integral` bounds, `where` `shape` constraints, variable/parameter `shape` lists, `Assertion.coords` keys, and `DataSourceSelectAxis.gated_by`. Keys must name an index set of the resolved mounted document (subsystem_index_set_rename_unknown_name); targets are dotted identifiers (template_import_rename_invalid) and must be distinct (template_import_rename_collision). The map need not be total: an unnamed axis passes through unrenamed, so a deliberately shared axis still merges deep-equal. Load-time only; consumed at the mount; does not survive parse→emit."
}
}
},
"Species": {
"type": "object",
"description": "A reactive species in a reaction system.",
"additionalProperties": false,
"properties": {
"units": {
"type": "string"
},
"default": {
"type": "number"
},
"default_units": {
"type": "string",
"description": "Units of the default value, if different from the declared units field. See ModelVariable.default_units for semantics."
},
"description": {
"type": "string"
},
"constant": {
"type": "boolean",
"default": false,
"description": "When true, the species participates in reactions as a reactant/product but its concentration is held fixed (no ODE integration) — a reservoir species. Maps to Catalyst's @species [isconstantspecies=true]. Absent or false means an ordinary state species with an ODE."
}
}
},
"Parameter": {
"type": "object",
"description": "A reaction-system parameter — rate constant, temperature, photolysis rate. Carries the same value machinery as a model `parameter`: a fixed `default`, or a `distribution`, with an optional `update` saying when it refreshes.",
"additionalProperties": false,
"properties": {
"units": {
"type": "string"
},
"default": {
"type": "number"
},
"default_units": {
"type": "string",
"description": "Units of the default value, if different from the declared units field. See ModelVariable.default_units for semantics."
},
"description": {
"type": "string"
},
"shape": {
"type": "array",
"items": {
"type": "string"
},
"description": "Arrayed-variable shape: ordered list of index-set names drawn from the document-scoped `index_sets` registry. Omitted or null indicates a scalar. REQUIRED for a parameter whose `update` is `schedule`, `data`, or `remesh` — such a parameter is a buffer whose extent is fixed at setup and refilled on a discrete cadence, so its extent must be known ahead of time (RFC semiring-faq-unified-ir §6.1); an empty array is a valid (scalar) shape."
},
"distribution": {
"$ref": "#/$defs/Distribution",
"description": "Draw this parameter's value from a distribution instead of fixing it at `default`. Mutually exclusive with `default`."
},
"update": {
"$ref": "#/$defs/ParameterUpdateSpec",
"description": "When this parameter refreshes and what it refreshes from."
}
},
"allOf": [
{
"if": {
"properties": {
"update": {
"anyOf": [
{
"type": "object",
"properties": {
"kind": {
"const": "wiener"
}
},
"required": [
"kind"
]
},
{
"type": "array",
"contains": {
"properties": {
"kind": {
"const": "wiener"
}
},
"required": [
"kind"
]
}
}
]
}
},
"required": [
"update"
]
},
"then": {
"required": [
"distribution"
]
}
},
{
"not": {
"required": [
"default",
"distribution"
]
}
},
{
"if": {
"properties": {
"update": {
"anyOf": [
{
"type": "object",
"properties": {
"kind": {
"enum": [
"schedule",
"data",
"remesh"
]
}
},
"required": [
"kind"
]
},
{
"type": "array",
"contains": {
"properties": {
"kind": {
"enum": [
"schedule",
"data",
"remesh"
]
}
},
"required": [
"kind"
]
}
}
]
}
},
"required": [
"update"
]
},
"then": {
"required": [
"shape"
]
}
}
]
},
"StoichiometryEntry": {
"type": "object",
"description": "A species with its stoichiometric coefficient in a reaction. Coefficients MUST be positive and finite (NaN / ±Infinity are rejected at parse time). Fractional values are supported to preserve fidelity with atmospheric-chemistry mechanisms whose products include non-integer yields (e.g. `0.87 CH2O`, `1.86 CH3O2`). Integer values remain valid — they are a subset of the permitted number range.",
"required": [
"species",
"stoichiometry"
],
"additionalProperties": false,
"properties": {
"species": {
"type": "string"
},
"stoichiometry": {
"type": "number",
"exclusiveMinimum": 0
}
}
},
"Reaction": {
"type": "object",
"description": "A single reaction in a reaction system.",
"required": [
"id",
"substrates",
"products",
"rate"
],
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"description": "Unique reaction identifier (e.g., \"R1\")."
},
"name": {
"type": "string"
},
"substrates": {
"description": "Array of {species, stoichiometry} or null for source reactions (∅ → X).",
"oneOf": [
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/StoichiometryEntry"
},
"minItems": 1
}
]
},
"products": {
"description": "Array of {species, stoichiometry} or null for sink reactions (X → ∅).",
"oneOf": [
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/StoichiometryEntry"
},
"minItems": 1
}
]
},
"rate": {
"$ref": "#/$defs/Expression",
"description": "Rate expression: a parameter reference string, number, or expression AST."
},
"reference": {
"$ref": "#/$defs/Reference"
}
}
},
"ReactionSystem": {
"type": "object",
"description": "A reaction network — declarative representation of chemical or biological reactions.",
"required": [
"species",
"parameters",
"reactions"
],
"additionalProperties": false,
"properties": {
"reference": {
"$ref": "#/$defs/Reference"
},
"species": {
"propertyNames": { "$ref": "#/$defs/Identifier" },
"type": "object",
"description": "Named reactive species.",
"additionalProperties": {
"$ref": "#/$defs/Species"
}
},
"parameters": {
"propertyNames": { "$ref": "#/$defs/Identifier" },
"type": "object",
"description": "Named parameters (rate constants, temperature, photolysis rates, etc.).",
"additionalProperties": {
"$ref": "#/$defs/Parameter"
}
},
"reactions": {
"type": "array",
"description": "Array of reaction definitions.",
"items": {
"$ref": "#/$defs/Reaction"
},
"minItems": 1
},
"constraint_equations": {
"type": "array",
"description": "Additional algebraic or ODE constraints.",
"items": {
"$ref": "#/$defs/Equation"
}
},
"discrete_events": {
"type": "array",
"items": {
"$ref": "#/$defs/DiscreteEvent"
}
},
"continuous_events": {
"type": "array",
"items": {
"$ref": "#/$defs/ContinuousEvent"
}
},
"subsystems": {
"propertyNames": { "$ref": "#/$defs/Identifier" },
"type": "object",
"description": "Named child reaction systems (subsystems), keyed by unique identifier. Enables hierarchical system composition. Variables in subsystems are referenced via dot notation: \"ParentSystem.ChildSystem.species\". Each subsystem can be defined inline or included by reference via a local file path or URL.",
"additionalProperties": {
"oneOf": [
{
"$ref": "#/$defs/ReactionSystem"
},
{
"$ref": "#/$defs/SubsystemRef"
}
]
}
},
"tolerance": {
"$ref": "#/$defs/Tolerance",
"description": "System-level default numerical tolerance for tests. Resolution is PER FIELD over four levels (esm-spec 6.6.4): assertion, test, system, then the implementation default (rel = 1e-6, no abs bound). abs and rel each take their value from the innermost level that declares that field, so a test or assertion that declares only one bound does not mask the other from here. An explicit 0 is a declaration ('no bound of this kind'), not an absence, and stops the fallthrough - including the fallthrough to the implementation default, which is why rel: 0 is the only way to ask for an absolute-only comparison."
},
"tests": {
"type": "array",
"description": "Inline validation tests that exercise this reaction system in isolation. Each test specifies initial conditions, parameter overrides, a time span, and scalar assertions at specific (species/variable, time) points.",
"items": {
"$ref": "#/$defs/Test"
}
},
"analyses": {
"type": "array",
"description": "Inline illustrative analyses of how to run this reaction system. Each analysis specifies initial state, parameters, a time span, an optional parameter sweep, and plot specifications.",
"items": {
"$ref": "#/$defs/Analysis"
}
},
"expression_templates": {
"propertyNames": { "$ref": "#/$defs/Identifier" },
"type": "object",
"description": "Component-scoped in-file Expression-AST templates (v0.4.0; docs/rfcs/ast-expression-templates.md). Each entry names a fixed Expression body with parameter substitution slots; `apply_expression_template` AST nodes elsewhere in this component (typically inside `reactions[*].rate`) reference the entry by key with per-parameter bindings. Templates are component-local: declarations here are visible only within this reaction system's expression positions. A body MAY reference other match-less in-scope templates as a statically-checked acyclic DAG — no cycles, no recursion (esm-spec §9.7.3). From esm 0.9.0 the round-trip is Option B (reference-preserving, esm-spec §9.6.4): references survive load and parse-then-emit and denote their expansion (`Expand`); eager (target-bearing) references still expand at load; emit materializes referenced templates into this registry — authored entries first in authored order, then materialized entries in lexicographic UTF-8 name order; keys may be dotted post-rename names. Pre-0.9.0 loaders expanded every reference at load (Option A) and emitted the expanded form.",
"additionalProperties": {
"$ref": "#/$defs/ExpressionTemplate"
}
},
"expression_template_imports": {
"type": "array",
"description": "Ordered imports of template-library files into this component's template scope (esm-spec §9.7.2). Imported templates join the §9.6.3 effective declaration order ahead of local declarations (§9.7.4).",
"items": {
"$ref": "#/$defs/TemplateImport"
}
}
}
},
"ExpressionTemplate": {
"type": "object",
"description": "A single in-file rewrite rule / Expression-AST template (esm-spec §9.6 / docs/rfcs/ast-expression-templates.md). The `params` are metavariables; the `body` is the replacement Expression AST in which parameter occurrences are written as bare parameter-name strings. The template is applied in one of two ways. (1) WITHOUT `match`: it is invoked explicitly by name through an `apply_expression_template` node, whose `bindings` supply each parameter's AST. (2) WITH `match`: it is an auto-applied rewrite rule — `match` is a pattern Expression in which parameters are wildcards (a parameter in an operand/`args` position binds to the matched sub-AST; a parameter in a scalar field such as `dim`/`side` binds to the matched literal), and the rule fires wherever the pattern structurally matches a node. This unifies variable substitution (a bare-metavar `match`), named-template expansion (no `match`), and rewrite-target-op lowering (an operator `match` like `{op:'D', args:['f'], wrt:'x'}` → a `faq`/`makearray` stencil). Either way the `body` is instantiated by pure structural substitution of the bound metavariables — no evaluation, no metaprogramming. Rewriting is an outermost-first, priority-ordered, bounded-fixpoint load-time process (esm-spec §9.6.3): each pass is a pre-order walk that fires, at each node, the matching rule of highest `priority` (ties broken by declaration order); passes repeat to a fixpoint or until MAX_REWRITE_PASSES=64, at which point a non-converging rule set is rejected with diagnostic 'rewrite_rule_nonterminating'. A rewrite-target op (esm-spec §4.2) surviving the fixpoint into an evaluation position is rejected with diagnostic 'unlowered_operator'. A `body` MAY contain `apply_expression_template` nodes referencing other match-less in-scope templates (declared locally or imported, esm-spec §9.7.2); these are checked at registration time as a statically-checked acyclic DAG (cycles rejected with 'apply_expression_template_recursive_body'; chains deeper than MAX_TEMPLATE_EXPANSION_DEPTH=32 rejected with 'template_body_expansion_too_deep'); from esm 0.9.0 they are preserved uninlined and denote their expansion (Option B, esm-spec §9.6.4; pre-0.9.0 loaders inlined them here by pure substitution). `match` patterns MUST NOT contain `apply_expression_template` nodes. An optional `where` block adds static match-scoping constraints on the captured parameters (declared-shape/index-set scoping, filtered before priority selection — see the `where` property and esm-spec §9.6.1).",
"required": [
"params",
"body"
],
"additionalProperties": false,
"properties": {
"params": {
"type": "array",
"description": "Ordered list of parameter (metavariable) names. MUST be unique within this template; MAY be empty (a zero-parameter template is a named constant fragment, common in library files). Each name occurs zero or more times inside `body` and (when present) `match`; for an explicitly-invoked template every name MUST also appear as a key in every `apply_expression_template.bindings` referencing it.",
"items": {
"type": "string",
"minLength": 1
},
"minItems": 0
},
"match": {
"$ref": "#/$defs/Expression",
"description": "Optional pattern Expression that turns this template into an auto-applied rewrite rule. Parameter names appearing as bare strings in `match` are wildcards bound by structural matching. A NON-parameter string in an operand/`args` position is a literal: it matches only that exact bare variable reference — the sanctioned per-variable selector (esm-spec §9.6.1/§9.6.8), e.g. {op:'D', args:['u'], wrt:'x'} with `u` not in `params` fires only on the derivative of `u`. Absent ⇒ the template is applied only via explicit `apply_expression_template` invocation."
},
"where": {
"type": "object",
"minProperties": 1,
"additionalProperties": {
"type": "object",
"required": [
"shape"
],
"additionalProperties": false,
"properties": {
"shape": {
"type": "array",
"minItems": 1,
"items": {
"type": "string",
"minLength": 1
}
}
}
},
"description": "Optional static match-scoping constraints for an auto-applied (`match`) rule (esm-spec §9.6.1; docs/rfcs/match-pattern-scoping-constraints.md). Keys are declared `params`; each value is a constraint object — the v1 vocabulary is exactly one kind, `shape`: an ordered list of index-set names as spelled in the CONSUMING document's merged index_sets registry (esm-spec §9.7.5, composing with import-edge index-set renaming). After the pattern structurally matches, the rule is eligible only if every constrained parameter bound to a BARE variable reference whose declaration in the enclosing component carries exactly that `shape` (same names, same order); a compound sub-AST, literal, scoped reference, undeclared name, or scalar fails the constraint. Evaluation is fully static — declared shapes at lowering time, never runtime values — and is part of match ELIGIBILITY: it filters BEFORE the §9.6.3 priority/declaration-order selection, so a constraint-excluded rule is simply a non-matching rule at that node. A constraint naming an index set absent from the consuming document's registry is rejected at rule registration with 'template_constraint_unknown_index_set'; a constrained rule that never fires is NOT an error (an un-lowered rewrite-target op is caught by the ordinary 'unlowered_operator' gate). Admissible only alongside `match` (else 'apply_expression_template_invalid_declaration')."
},
"priority": {
"type": "integer",
"default": 0,
"description": "Selection precedence for an auto-applied (`match`) rule (esm-spec §9.6.3). When more than one rule matches a node, the highest `priority` wins; ties break by declaration order. This lets a compound-term rule (Godunov / WENO / flux-limited) out-rank the plain per-derivative rule so it fires on the whole compound before the inner derivatives are lowered. Ignored when `match` is absent. Absent ⇒ 0."
},
"body": {
"$ref": "#/$defs/Expression",
"description": "The replacement Expression AST. Parameter names appear as bare strings and are replaced structurally with their bound argument (from `match` or from `apply_expression_template.bindings`) at expansion time."
},
"description": {
"type": "string"
}
}
},
"TemplateImport": {
"type": "object",
"description": "One entry of `expression_template_imports` (esm-spec §9.7.2): imports the templates (and index_sets / open metaparameters) of a template-library file. `ref` uses the §4.7 reference formats (relative path, absolute path, or URL), resolved at load before validation with canonical-path cycle detection (`template_import_cycle`). `only` filters which template names become visible to the importer (`template_import_unknown_name` for unknown names). `bindings` closes the target document's open metaparameters to integers at this edge (esm-spec §9.7.6); metaparameters left unbound are re-exported into the importing document's scope. `prefix` / `rename` namespace the surviving exported names (templates after `only`, index sets, still-open metaparameters) into the importer's vocabulary, applied transitively through every occurrence inside the imported declarations; `rebind` rewrites free variable names (keyed factors and other free names in template bodies) at the same point (esm-spec §9.7.7). Renaming happens after this edge's `bindings` instantiation and `only` filtering and before the §9.7.4/§9.7.5 merge, so the same file imported under different renames registers as distinct instances while identical edges dedupe. Identifier grammar, unknown-name, and collision checks are resolver-level (`template_import_rename_invalid`, `template_import_rename_unknown_name`, `template_import_rebind_unknown_name`, `template_import_rename_collision`).",
"required": [
"ref"
],
"additionalProperties": false,
"properties": {
"ref": {
"type": "string",
"minLength": 1,
"description": "Path or URL of a template-library file, per the §4.7 reference-format table."
},
"only": {
"type": "array",
"minItems": 1,
"uniqueItems": true,
"items": {
"type": "string",
"minLength": 1
},
"description": "Template names to import; absent = all."
},
"bindings": {
"type": "object",
"additionalProperties": {
"$ref": "#/$defs/MetaparameterExpression"
},
"description": "Bindings closing the target document's metaparameters at this edge (esm-spec §9.7.6 site 1). Each value is a metaparameter expression over the importing document's metaparameters; a value with still-open names is carried symbolically and folds at the importer's close."
},
"prefix": {
"type": "string",
"minLength": 1,
"description": "Namespace prefix: every surviving exported name without an explicit `rename` entry is renamed to `<prefix>.<name>` (esm-spec §9.7.7). Grammar (resolver-enforced): dotted identifier segments [A-Za-z_][A-Za-z0-9_]*."
},
"rename": {
"type": "object",
"additionalProperties": {
"type": "string",
"minLength": 1
},
"description": "Explicit renames, exported name → importer-visible name; entries override `prefix`. Keys must name a surviving export (`template_import_rename_unknown_name`); targets are dotted identifiers (esm-spec §9.7.7)."
},
"rebind": {
"type": "object",
"additionalProperties": {
"type": "string",
"minLength": 1
},
"description": "Free-name rebinding, free name → replacement variable name (e.g. areaCell → meshA.areaCell): rewrites free variable names occurring in the imported template bodies/matches and ragged index-set offsets/values factors. Keys must occur free in the surviving declarations (`template_import_rebind_unknown_name`) (esm-spec §9.7.7)."
}
}
},
"Metaparameters": {
"propertyNames": { "$ref": "#/$defs/Identifier" },
"type": "object",
"description": "Document-scoped named integers bound at load (esm-spec §9.7.6): at import/subsystem edges via `bindings`, at the loader API for the root document, or by `default`. Admissible — as names or `{op, args}` integer expressions — in `index_sets` interval sizes, `faq` dense ranges, and `makearray` regions (folded exactly at load), and substituted as integer literals in ordinary expression positions. A metaparameter name MUST NOT collide with any visible variable/parameter/species/index-set name (`metaparameter_name_conflict`).",
"additionalProperties": {
"type": "object",
"required": [
"type"
],
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"const": "integer",
"description": "The only v1 metaparameter kind."
},
"default": {
"type": "integer",
"description": "Fallback applied at root resolution, after edge and loader-API bindings; a still-open metaparameter with no default is `metaparameter_unbound`."
},
"description": {
"type": "string"
}
}
}
},
"MetaparameterExpression": {
"description": "A load-time integer expression over metaparameters (esm-spec §9.7.6): an integer literal, a declared metaparameter name, or `{op: +|-|*|/, args: [...]}` over metaparameter expressions (unary `-` allowed). Folded to a concrete integer at load with exact 64-bit arithmetic; `/` MUST divide exactly and overflow is an error (`metaparameter_type_error`). Admissible in structural integer sites (`index_sets` interval `size`, `faq` dense `ranges` tuple entries, `makearray` `regions` bound pairs) AND as an import-edge / subsystem-edge binding VALUE, whose free names resolve in the importing document's metaparameter scope.",
"oneOf": [
{
"type": "integer"
},
{
"type": "string",
"minLength": 1
},
{
"type": "object",
"required": [
"op",
"args"
],
"additionalProperties": false,
"properties": {
"op": {
"type": "string",
"enum": [
"+",
"-",
"*",
"/"
]
},
"args": {
"type": "array",
"minItems": 1,
"items": {
"$ref": "#/$defs/MetaparameterExpression"
}
}
}
}
]
},
"Solver": {
"type": "object",
"description": "Document-scoped, OPTIONAL solver hints (esm-spec §2.2): numerics the document knows about ITSELF, which each binding maps to its own integrator. Purely additive — a document without it validates, flattens and emits exactly as before. Every field is ADVISORY: a binding MAY ignore any or all of them and still conform. Advisory governs the MECHANISM, never the OUTCOME — a binding that ignores every field and still converges conforms; the requirement to integrate successfully and agree within the CONFORMANCE_SPEC §5.9 error band is untouched by this block and is not excused by it. What IS normative: parse it, validate it, round-trip it VERBATIM (it is authored configuration, a peer of `tolerance` and `parameter_overrides` — not a load-time construct like `expression_template_imports`), leave the flattened system unchanged, and reject it in a document declaring `esm` below 1.1.0 with `solver_version_too_old` (and reject `external` or `time_span` in a document declaring `esm` below 1.3.0 with `solver_external_version_too_old` / `solver_time_span_version_too_old`). This block is NOT for algorithm names (`BDF`/`LSODA`/`Rosenbrock23` are per-binding identifiers and would not be portable — there is deliberately no `alg` field), NOT for binding-specific compile knobs (`cse` is a sympy.lambdify concern), and NOT a DAE declaration (`system_class` is DERIVED from the equation set). An empty block (`\"solver\": {}`) is LEGAL and means exactly what absence means; it NORMALIZES to absence at load, so it does not survive `parse -> emit` and the typed value never holds a block with nothing set. That normalization is why the schema does NOT carry `minProperties: 1`: every other optional top-level container (`coordinates`, `index_sets`, `metaparameters`, `coupling_roles`) admits an empty object, and a lone exception here would be a rule a reader has to learn for no gain. Arrives at esm 1.1.0.",
"additionalProperties": false,
"properties": {
"stiffness": {
"enum": [
"low",
"moderate",
"high"
],
"description": "The author's declaration of the system's stiffness. A binding MAY select an implicit / BDF-family integrator on `high`. ABSENCE IS NOT A DEFAULT VALUE: a document that omits this key has not declared its stiffness and does not thereby declare `low`; bindings MUST NOT read absence as an assertion about the system. The motivating case is the POLLU stiff-ODE benchmark (Verwer 1994), whose rate constants span ~8e-7 to ~7e9 1/s: scipy's LSODA cannot integrate it at all while BDF reproduces the published reference, a fact that is true of the MODEL rather than of any runner."
},
"abstol": {
"type": "number",
"exclusiveMinimum": 0,
"description": "Absolute INTEGRATION tolerance the document asks for. Spelled as the `solve()` keyword (API_SPEC §4) so it passes through literally. This is a DIFFERENT QUANTITY from the `tolerance` object on a model / reaction system / test / assertion (esm-spec §6.6.4), which is the tolerance an assertion is COMPARED at; the two resolve independently and neither substitutes for the other. Resolution order, most-specific first: an explicit argument at the `solve()` call site, then this field, then the binding default (1e-6)."
},
"reltol": {
"type": "number",
"exclusiveMinimum": 0,
"description": "Relative INTEGRATION tolerance the document asks for. Same resolution order and the same distinction from the assertion-comparison `tolerance` object as `abstol`; the binding default is 1e-4."
},
"splitting": {
"enum": [
"none",
"lie",
"strang"
],
"description": "Advisory: the system tolerates or benefits from this operator-splitting convention. Carries NO prescribed substep structure and does not amend esm-spec §9's single-flat-system model — a binding that does not split ignores it. The vocabulary is deliberately the one the discretization RFC §7.5 dimensional-splitting field already uses, so the word means one thing across the spec, even though that occurrence is executable and this one is a hint."
},
"external": {
"type": "string",
"minLength": 1,
"description": "Reference to an external run-configuration document (esm-spec §2.2.6). Relative paths resolve against the directory of the file this document was read from. EarthSciAST never opens it. Round-trips verbatim. Arrives at esm 1.3.0."
},
"time_span": {
"type": "object",
"additionalProperties": false,
"required": [
"start",
"end"
],
"description": "The interval the document's author means it to be simulated over (esm-spec §2.2.7): the same `{start, end}` shape as `tests[].time_span`. ADVISORY like every `solver` field; a binding that honours it MUST let an explicit interval at the call site win. Round-trips verbatim. Arrives at esm 1.3.0.",
"properties": {
"start": {
"oneOf": [
{
"type": "number"
},
{
"type": "string",
"pattern": "^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9](\\.[0-9]+)?Z$"
}
],
"description": "Beginning of the interval: a number in the document's time units (seconds of the independent variable), or an RFC 3339 UTC timestamp (`Z` required, no offset), which means seconds since the document's time origin (esm-spec §2.2.7)."
},
"end": {
"oneOf": [
{
"type": "number"
},
{
"type": "string",
"pattern": "^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9](\\.[0-9]+)?Z$"
}
],
"description": "End of the interval: a number in the document's time units (seconds of the independent variable), or an RFC 3339 UTC timestamp (`Z` required, no offset), which means seconds since the document's time origin (esm-spec §2.2.7). MUST be after `start` once both are converted; a load-time check (`solver_time_span_invalid`), since the schema cannot compare a timestamp with a number."
}
}
}
}
},
"Tolerance": {
"type": "object",
"description": "Numerical comparison tolerance. Any of abs/rel may be specified. If both are given, an assertion passes when either bound is satisfied: |actual - expected| <= abs OR |actual - expected| <= rel * max(|actual|, |expected|). The relative bound is SYMMETRIC -- it scales by the larger of the two magnitudes, not by |expected| alone (Julia `isapprox`; esm-spec 6.6.3). Finiteness is judged before tolerance: a non-finite actual fails against every finite expected, at every tolerance.",
"additionalProperties": false,
"properties": {
"abs": {
"type": "number",
"minimum": 0,
"description": "Absolute tolerance: |actual - expected| <= abs."
},
"rel": {
"type": "number",
"minimum": 0,
"description": "Relative tolerance: |actual - expected| <= rel * max(|actual|, |expected|). Symmetric in actual and expected -- the scale is the larger of the two magnitudes, not |expected| alone."
}
}
},
"Assertion": {
"type": "object",
"description": "A single scalar check against a model variable at a specific (variable, time) point. PDE-aware variants pin a spatial point via `coords`, or reduce the field to a scalar via `reduce` (domain-integral, mean, max, min, or error-norm). `coords` and `reduce` are mutually exclusive; if neither is given the assertion is pointwise and is valid only on a variable declared without a `shape` or on an element name such as `u[1]` (esm-spec §6.6.5). Error-norm reductions (L2_error, Linf_error) require `reference`.",
"required": [
"variable",
"time"
],
"additionalProperties": false,
"properties": {
"variable": {
"type": "string",
"description": "Name of the variable or species to check. Use the local name (e.g., \"O3\") or a scoped reference relative to this component (e.g., \"subsystem.X\")."
},
"time": {
"type": "number",
"description": "Simulation time at which to evaluate the assertion. Must lie within [time_span.start, time_span.end]."
},
"expected": {
"type": "number",
"description": "Expected scalar value of the variable at the given time."
},
"tolerance": {
"$ref": "#/$defs/Tolerance",
"description": "Per-assertion tolerance override, merged PER FIELD over the test-level and model-level defaults and then the implementation default (esm-spec 6.6.4): each of abs and rel that this object declares wins, and each it omits falls through independently. Declaring only abs here therefore keeps an outer rel rather than dropping it, and falls through to the implementation default rel = 1e-6 when no enclosing level declares one; write rel: 0 to mean 'no relative bound'."
},
"coords": {
"type": "object",
"description": "Spatial-point evaluation: map from a spatial index-set / dimension name (e.g., \"x\", \"lon\") to the numeric coordinate at which to sample the field. All keys MUST be names of index sets the field is defined over. Mutually exclusive with `reduce`.",
"additionalProperties": {
"type": "number"
},
"minProperties": 1
},
"reduce": {
"type": "string",
"description": "Domain reduction: collapse the spatial field to a single scalar before comparison. `integral`/`mean`/`max`/`min` are pure reductions; `L2_error`/`Linf_error` require a `reference` solution and compute ||u_actual - u_reference||_norm. Mutually exclusive with `coords`.",
"enum": [
"integral",
"mean",
"max",
"min",
"L2_error",
"Linf_error"
]
},
"reference": {
"description": "Reference (analytic or precomputed) solution required by error-norm reductions. Either an inline Expression evaluated over the component's domain coordinates, or a from_file shape pointing at a precomputed snapshot.",
"oneOf": [
{
"$ref": "#/$defs/Expression"
},
{
"type": "object",
"required": [
"type",
"path"
],
"additionalProperties": false,
"properties": {
"type": {
"const": "from_file"
},
"path": {
"type": "string"
},
"format": {
"type": "string"
}
}
}
]
}
},
"allOf": [
{
"not": {
"required": [
"coords",
"reduce"
]
}
},
{
"required": [
"expected"
]
},
{
"if": {
"properties": {
"reduce": {
"enum": [
"L2_error",
"Linf_error"
]
}
},
"required": [
"reduce"
]
},
"then": {
"required": [
"reference"
]
}
},
{
"if": {
"properties": {
"reduce": {
"enum": [
"integral",
"mean",
"max",
"min"
]
}
},
"required": [
"reduce"
]
},
"then": {
"not": {
"required": [
"reference"
]
}
}
}
]
},
"Test": {
"type": "object",
"description": "An inline validation test for the enclosing model or reaction system. Defines the run configuration (initial conditions, parameter overrides, time span) and the scalar assertions that must hold.",
"required": [
"id",
"time_span",
"assertions"
],
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"description": "Identifier unique within this component's tests array."
},
"description": {
"type": "string",
"description": "Human-readable description of what this test verifies."
},
"initial_conditions": {
"type": "object",
"description": "Initial-value overrides for unknowns, keyed by variable name (local to this component). Values not listed fall back to the variable's declared default. A shaped unknown's value may be a row-major nested JSON array matching its declared shape (esm-spec §6.6.2).",
"additionalProperties": {
"oneOf": [
{
"type": "number"
},
{
"$ref": "#/$defs/NumericArrayLiteral"
}
],
"description": "Initial value for one unknown: a number, or — for a SHAPED unknown — a row-major nested JSON array matching its declared shape after metaparameter folding (a mismatch is a load-time error). A scalar broadcasts to every element (esm-spec §6.6.2)."
}
},
"parameter_overrides": {
"type": "object",
"description": "Parameter overrides, keyed by parameter name (local to this component). Values not listed fall back to the parameter's declared default. A shaped parameter's value may be a row-major nested JSON array matching its declared shape (esm-spec §6.6.2).",
"additionalProperties": {
"oneOf": [
{
"type": "number"
},
{
"$ref": "#/$defs/NumericArrayLiteral"
}
],
"description": "Value for one parameter: a number, or — for a SHAPED parameter — a row-major nested JSON array matching its declared shape after metaparameter folding (a mismatch is a load-time error). A scalar broadcasts to every element (esm-spec §6.6.2)."
}
},
"time_span": {
"$ref": "#/$defs/TimeSpan"
},
"tolerance": {
"$ref": "#/$defs/Tolerance",
"description": "Test-level default tolerance, merged PER FIELD (esm-spec 6.6.4): it supplies each of abs and rel that an assertion in this test does not declare, and falls through to the model-level default - and then to the implementation default rel = 1e-6 - for each field it does not declare itself. Write rel: 0 to stop that fallthrough."
},
"expression_template_imports": {
"type": "array",
"description": "Template-library imports registered into the ENCLOSING component's template scope for THIS run only (esm-spec §9.7.10 / §6.6) — lets a discretization-agnostic PDE component's inline tests run under a per-test discretization chosen without editing the leaf. Same entry shape as §9.7.2; target implicit (the enclosing component). Execution-time (ephemeral per-run build); authored per-run configuration, so it DOES survive parse→emit (peer of parameter_overrides / tolerance).",
"items": {
"$ref": "#/$defs/TemplateImport"
}
},
"assertions": {
"type": "array",
"description": "Scalar (variable, time) checks that define the pass/fail criterion of the test.",
"items": {
"$ref": "#/$defs/Assertion"
},
"minItems": 1
}
}
},
"TimeSpan": {
"type": "object",
"description": "Simulation time interval expressed in the component's time units.",
"required": [
"start",
"end"
],
"additionalProperties": false,
"properties": {
"start": {
"type": "number"
},
"end": {
"type": "number"
}
}
},
"SweepRange": {
"type": "object",
"description": "Generated range of parameter values.",
"required": [
"start",
"stop",
"count"
],
"additionalProperties": false,
"properties": {
"start": {
"type": "number"
},
"stop": {
"type": "number"
},
"count": {
"type": "integer",
"minimum": 2
},
"scale": {
"type": "string",
"enum": [
"linear",
"log"
],
"default": "linear",
"description": "Spacing: linear = evenly spaced between start and stop; log = logarithmically spaced (start and stop must be strictly positive)."
}
}
},
"SweepDimension": {
"type": "object",
"description": "One axis of a parameter sweep: exactly one of values or range must be given.",
"required": [
"parameter"
],
"additionalProperties": false,
"properties": {
"parameter": {
"type": "string",
"description": "Name of the parameter to vary (local to this component)."
},
"values": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 1,
"description": "Enumerated values to use for this axis."
},
"range": {
"$ref": "#/$defs/SweepRange",
"description": "Generated range; mutually exclusive with values."
}
},
"oneOf": [
{
"required": [
"values"
]
},
{
"required": [
"range"
]
}
]
},
"ParameterSweep": {
"type": "object",
"description": "A parameter sweep specification. Currently only Cartesian product sweeps are supported — the total run count is the product of each dimension's length.",
"required": [
"type",
"dimensions"
],
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"enum": [
"cartesian"
],
"description": "Sweep combination strategy. Currently only cartesian (full Cartesian product) is supported."
},
"dimensions": {
"type": "array",
"items": {
"$ref": "#/$defs/SweepDimension"
},
"minItems": 1
}
}
},
"PlotAxis": {
"type": "object",
"description": "Axis specification: any unknown, parameter name, or swept parameter may be used.",
"required": [
"variable"
],
"additionalProperties": false,
"properties": {
"variable": {
"type": "string",
"description": "Variable or parameter name (local to this component or scoped within a subsystem)."
},
"label": {
"type": "string",
"description": "Human-readable axis label. Viewers should fall back to the variable name if omitted."
}
}
},
"PlotValue": {
"type": "object",
"description": "A scalar value derived from a trajectory: used for heatmap z / color channels. Exactly one of at_time or reduce should be specified; if both are given, at_time takes precedence.",
"required": [
"variable"
],
"additionalProperties": false,
"properties": {
"variable": {
"type": "string",
"description": "Variable whose trajectory is reduced to a scalar per run."
},
"at_time": {
"type": "number",
"description": "Specific simulation time at which to sample the variable."
},
"reduce": {
"type": "string",
"enum": [
"max",
"min",
"mean",
"integral",
"final"
],
"description": "Time-reduction applied to the trajectory: max/min/mean over the run, time integral, or the final value at time_span.end."
}
}
},
"PlotSeries": {
"type": "object",
"description": "A single named series for multi-series line or scatter plots.",
"required": [
"name",
"variable"
],
"additionalProperties": false,
"properties": {
"name": {
"type": "string"
},
"variable": {
"type": "string"
}
}
},
"Plot": {
"type": "object",
"description": "A plot specification associated with an analysis. Only structural information is recorded — axes, series selection, and value reductions. Styling (colors, fonts, legends, themes) is the viewer's concern. PDE-aware plot types `field_slice` and `field_snapshot` visualize spatial fields at a fixed time; `x` (and `y` for snapshots) name domain dimensions, the variable value becomes the y / color channel, and any non-plotted spatial dimension MUST be pinned in `pinned_coords`.",
"required": [
"id",
"type",
"x",
"y"
],
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"description": "Identifier unique within this analysis's plots array."
},
"type": {
"type": "string",
"enum": [
"line",
"scatter",
"heatmap",
"field_slice",
"field_snapshot"
]
},
"description": {
"type": "string"
},
"x": {
"$ref": "#/$defs/PlotAxis"
},
"y": {
"description": "Y-axis specification. May be a single PlotAxis, or an array of PlotAxis for inline multi-series line/scatter plots (alternative to the `series` field for the common case of plotting several variables against a shared x-axis).",
"oneOf": [
{
"$ref": "#/$defs/PlotAxis"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/PlotAxis"
},
"minItems": 1
}
]
},
"value": {
"$ref": "#/$defs/PlotValue",
"description": "Required for heatmap; defines the color channel. Ignored for line/scatter. For field_snapshot, the variable plotted as the color channel (use `value.variable`); `at_time` and `reduce` are ignored — the field is sampled at `at_time` declared on the plot."
},
"series": {
"type": "array",
"description": "Multiple named series for line or scatter plots. Ignored for heatmap and field plots.",
"items": {
"$ref": "#/$defs/PlotSeries"
}
},
"at_time": {
"type": "number",
"description": "Required for field_slice and field_snapshot: simulation time at which to extract the spatial field. Must lie within the analysis's time_span."
},
"pinned_coords": {
"type": "object",
"description": "Required for field_slice and field_snapshot when the component domain has more spatial dimensions than the plot's spatial axes (1 for field_slice, 2 for field_snapshot). Maps each non-plotted spatial dimension name to the numeric coordinate at which to slice. Keys MUST be names of dimensions in component.domain.spatial that are not used by `x` (or `y` for field_snapshot).",
"additionalProperties": {
"type": "number"
}
},
"contours": {
"type": "array",
"description": "Optional iso-levels to overlay as contour lines on a field plot (field_slice / field_snapshot / heatmap). Each number is a value of the plotted field at which to draw a contour line — e.g. [0] draws the zero level-set front. Purely a viewer overlay; ignored for line/scatter.",
"items": {
"type": "number"
}
}
},
"allOf": [
{
"if": {
"properties": {
"type": {
"const": "heatmap"
}
},
"required": [
"type"
]
},
"then": {
"required": [
"value"
]
}
},
{
"if": {
"properties": {
"type": {
"const": "field_slice"
}
},
"required": [
"type"
]
},
"then": {
"required": [
"at_time"
]
}
},
{
"if": {
"properties": {
"type": {
"const": "field_snapshot"
}
},
"required": [
"type"
]
},
"then": {
"required": [
"at_time",
"value"
]
}
}
]
},
"Analysis": {
"type": "object",
"description": "An inline illustrative analysis of how to run the enclosing component. Defines the run configuration and one or more plots derived from the result.",
"required": [
"id",
"time_span"
],
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"description": "Identifier unique within this component's analyses array."
},
"description": {
"type": "string",
"description": "Human-readable description of what this analysis illustrates."
},
"initial_state": {
"description": "Initial state for this analysis run. Either (legacy) a flat map of scalar overrides keyed by state-variable name, or the esm-spec §11.4 discriminated union: {type:\"per_variable\", values:{name:number}} for scalar ICs, or {type:\"expression\", values:{name:<expression>}} for closed-form spatial FIELD initial conditions (per-cell coordinate expressions). Field ICs may also be declared with `ic` equations in the model.",
"oneOf": [
{
"type": "object",
"description": "Legacy flat scalar-override map (state-variable name -> value).",
"additionalProperties": {
"type": "number"
}
},
{
"type": "object",
"description": "Discriminated union (esm-spec §11.4).",
"additionalProperties": false,
"required": [
"type",
"values"
],
"properties": {
"type": {
"enum": [
"per_variable",
"expression"
]
},
"values": {
"type": "object",
"description": "For type=per_variable each value is a scalar number; for type=expression each value is an expression AST (a closed-form per-cell field over the state's index sets)."
}
}
}
]
},
"parameters": {
"type": "object",
"description": "Parameter overrides, keyed by parameter name (local to this component).",
"additionalProperties": {
"type": "number"
}
},
"time_span": {
"$ref": "#/$defs/TimeSpan"
},
"parameter_sweep": {
"$ref": "#/$defs/ParameterSweep",
"description": "Optional parameter sweep. When present, the analysis represents a family of runs (one per Cartesian combination) rather than a single trajectory."
},
"plots": {
"type": "array",
"description": "Plot specifications derived from this analysis's run(s).",
"items": {
"$ref": "#/$defs/Plot"
}
},
"expression_template_imports": {
"type": "array",
"description": "Template-library imports registered into the ENCLOSING component's template scope for THIS run only (esm-spec §9.7.10 / §6.7) — lets a discretization-agnostic PDE component's inline analyses run under a per-run discretization chosen without editing the leaf. Same entry shape as §9.7.2; target implicit (the enclosing component). Execution-time (ephemeral per-run build); authored per-run configuration, so it DOES survive parse→emit (peer of parameters / parameter_sweep).",
"items": {
"$ref": "#/$defs/TemplateImport"
}
}
}
},
"DataSourceLocation": {
"type": "object",
"description": "File discovery configuration. Describes how to locate data files at runtime via URL templates with date/variable substitutions.",
"required": [
"url_template"
],
"additionalProperties": false,
"properties": {
"url_template": {
"type": "string",
"description": "Jinja-style URL template with substitutions. Supported: {date:<strftime>} (e.g. {date:%Y%m%d}), {var}, {sector}, {species}. Custom substitutions are allowed and the runtime must accept and pass them through."
},
"mirrors": {
"type": "array",
"description": "Ordered fallback URL templates. Runtime tries each in order, first is primary. Follows the same substitution grammar as url_template.",
"items": {
"type": "string"
}
}
}
},
"DataSourceTemporal": {
"type": "object",
"description": "Temporal coverage and record layout for a data source.",
"additionalProperties": false,
"properties": {
"start": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 datetime — first timestamp available from this source."
},
"end": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 datetime — last timestamp available from this source."
},
"file_period": {
"type": "string",
"description": "ISO 8601 duration describing how much time one file covers (e.g., \"P1D\", \"P1M\", \"PT3H\")."
},
"frequency": {
"type": "string",
"description": "ISO 8601 duration describing spacing between samples within a file."
},
"records_per_file": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"enum": [
"auto"
]
}
],
"description": "Number of time records per file. \"auto\" means read from file at runtime."
},
"time_variable": {
"type": "string",
"description": "Name of the time coordinate variable in the file. Used when records_per_file is absent or \"auto\". If both static declarations (records_per_file + frequency) and time_variable are present, the static declaration wins and time_variable is a fallback."
},
"records_per_sample": {
"type": "integer",
"enum": [
1,
2
],
"description": "How many time records the source returns per query time — pure I/O; the source does NOT interpolate. Absent or 1 (default): the single at-or-before record, time axis dropped (piecewise-constant between ticks). 2: the two records bracketing the current time (floor + successor), returned with the time axis kept at length 2 so a downstream model can interpolate in time (e.g. linearly). Only 1 and 2 are supported; higher-order temporal stencils are future work. Contrast records_per_file (records IN one file)."
}
}
},
"DataSourceCodes": {
"type": "object",
"description": "Maps a TEXT source column to the numbers a model can compute with — an FF10 `POLID` string (\"NOX\", \"SO2\", ...) to the pollutant enum integer the `is_NOx`/`is_SOx` membership unknowns compare against. Without it a text column is a hard error at the ingest boundary, because a model forcing must be numeric. This is decoding a code, not converting a unit: `unit_conversion` scales a number that is already one.",
"required": [
"map"
],
"additionalProperties": false,
"properties": {
"map": {
"type": "object",
"description": "Source value -> number.",
"minProperties": 1,
"additionalProperties": {
"type": "number"
}
},
"case_insensitive": {
"type": "boolean",
"default": false,
"description": "Compare upper-cased on both sides. Surrounding whitespace is always trimmed, on both sides, regardless."
},
"unmapped": {
"oneOf": [
{
"enum": [
"drop",
"error"
]
},
{
"type": "number"
}
],
"default": "error",
"description": "What a value absent from `map` does: \"error\" (the default, fail-closed) rejects the load naming the value; \"drop\" removes the whole RECORD from EVERY variable of the loader — which is why it is a record-level decision and not a per-column one; a number substitutes that code."
}
}
},
"DataSourceSelect": {
"type": "object",
"description": "A per-axis selection of what the source DELIVERS from an on-disk array — one entry per NATIVE array dimension, in native dims order. Declared on a source (the default for every parameter drawing from it) or on a single parameter's `from` binding (which overrides the source's). Two parameters of one source MAY read the same `file_variable` under different selections, which is how a full-grid field and a prefix of it are both declared instead of one being sliced by the caller. The selection is defined over the axis the loader DELIVERS, so it follows any `record_filter`: `range 0..200` on a filtered points table is the first 200 SURVIVING records. Whether a binding pushes it down to the reader (fetching only what it keeps) or applies it after the read is an optimization; the two MUST agree exactly.",
"required": [
"axes"
],
"additionalProperties": false,
"properties": {
"axes": {
"type": "array",
"description": "One selector per native array dimension, in native dims order.",
"minItems": 1,
"items": {
"$ref": "#/$defs/DataSourceSelectAxis"
}
}
}
},
"DataSourceSelectAxis": {
"description": "One native axis of a `DataLoaderSelect`. The vocabulary is shared with the projection-pushdown gate template (CONFORMANCE_SPEC §5.5): \"all\" keeps the axis whole; `fixed` takes one index and DROPS the axis; `range` takes a half-open strided window and keeps it; `gated_by` names a `derived` index set whose value-invention members become the axis, which DEFERS the fetch until those members exist.",
"oneOf": [
{
"const": "all",
"description": "The whole axis."
},
{
"type": "object",
"description": "Take one index; the axis is DROPPED from the delivered array (it is a choice, not a dimension).",
"required": [
"fixed"
],
"additionalProperties": false,
"properties": {
"fixed": {
"oneOf": [
{
"type": "integer",
"minimum": 0
},
{
"type": "array",
"minItems": 1,
"maxItems": 1,
"items": {
"type": "integer",
"minimum": 0
}
}
],
"description": "A single 0-based native index."
}
}
},
{
"type": "object",
"description": "Take a half-open strided window `[start, stop)` and keep the axis.",
"required": [
"range"
],
"additionalProperties": false,
"properties": {
"range": {
"type": "object",
"required": [
"stop"
],
"additionalProperties": false,
"properties": {
"start": {
"oneOf": [
{
"type": "integer",
"minimum": 0
},
{
"type": "string"
}
],
"description": "Inclusive first index (default 0). A string names a `metaparameters` entry and resolves to its closed value (esm-spec §9.7.6)."
},
"stop": {
"oneOf": [
{
"type": "integer",
"minimum": 0
},
{
"type": "string"
}
],
"description": "Exclusive last index. A string names a `metaparameters` entry and resolves to its closed value (esm-spec §9.7.6), so a prefix is declared in the model's own terms (`W[0:N_SRC]`) rather than as a repeated literal that can drift from the index set sized by the same metaparameter."
},
"step": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string"
}
],
"description": "Stride (default 1; MUST be >= 1)."
}
}
}
}
},
{
"type": "object",
"description": "Gate the axis on a derived index set; the fetch is deferred past value-invention and delivered pre-sliced.",
"required": [
"gated_by"
],
"additionalProperties": false,
"properties": {
"gated_by": {
"type": "string",
"description": "Name of a `kind: \"derived\"` index set. The axis becomes that set's materialised members in canonical (sorted) member order (CONFORMANCE_SPEC §5.5, Hook 2), so only the rows the model can reach are ever read."
}
}
}
]
},
"DataSourceRecordFilter": {
"type": "object",
"description": "Which records of a `points` source are DELIVERED. The surviving mask is computed ONCE for the source and applied to every parameter drawing from it, so its columns can never fall out of alignment, and the surviving count is the source's `extent`. A record is dropped when any `require_finite` variable is non-finite at it, or when a `codes` map with `unmapped: \"drop\"` does not recognise its value.",
"additionalProperties": false,
"properties": {
"require_finite": {
"type": "array",
"description": "`file_variable` names whose value must be finite for a record to survive. (Pre-1.0.0 this named loader variable names; a source has no variables of its own now, so it names the file's.) A point with no coordinate cannot be placed and a row with no annual total cannot be weighted; dropping it is a declaration about the source, rather than a NaN travelling into the model to surface as an empty result later.",
"minItems": 1,
"items": {
"type": "string"
}
}
}
},
"DataSourceExtent": {
"type": "object",
"description": "Binds the source's DELIVERED record count to a metaparameter, for a source whose extent is not knowable until it is read. A binding samples such a source BEFORE it closes metaparameters (esm-spec §9.7.6 site 4), so an index set declared `size: \"N_REC\"` is sized by the data itself and no caller counts rows and passes the number in. Every parameter drawing from the source MUST agree on the count — that agreement is also the alignment check.",
"required": [
"metaparameter"
],
"additionalProperties": false,
"properties": {
"metaparameter": {
"type": "string",
"description": "Name of the `metaparameters` entry it binds. Declare that entry with a `default` (conventionally 0) so the document still validates and loads standalone."
}
}
},
"DataSourceDeterminism": {
"type": "object",
"description": "Reproducibility contract a binary-format loader advertises to bindings. A binding that cannot honor the declared endian / float_format / integer_width MUST reject the file at load rather than silently reinterpreting bytes.",
"additionalProperties": false,
"properties": {
"endian": {
"type": "string",
"enum": [
"little",
"big"
],
"description": "Byte order of on-wire numeric fields."
},
"float_format": {
"type": "string",
"enum": [
"ieee754_single",
"ieee754_double"
],
"description": "Floating-point format of metric fields."
},
"integer_width": {
"type": "integer",
"enum": [
32,
64
],
"description": "Integer width (in bits) of connectivity fields."
}
}
},
"DataSource": {
"type": "object",
"description": "A named external data source reduced to pure I/O: it locates, reads, decodes, slices, and filters bytes on disk. It performs no reprojection and no regridding, and — from 1.0.0 — it exposes no variables and is NOT a component. It cannot be a coupling endpoint, a subsystem, or a scoped-name path root; a model consumes it by declaring a parameter whose `update` names this source and binds one of its `file_variable`s. Grid geometry a source reads (coordinates, connectivity, metric arrays) arrives as ordinary parameters and is transformed downstream by `faq` nodes and coupling expressions. Authentication and algorithm-specific tuning are runtime-only and not part of the schema.",
"required": [
"kind",
"source"
],
"additionalProperties": false,
"properties": {
"kind": {
"type": "string",
"enum": [
"grid",
"points",
"static"
],
"description": "Structural kind of the dataset: 'grid' (gridded array source), 'points' (scattered point/station source), or 'static' (time-invariant source). Grid geometry the source reads — coordinates, connectivity, metric arrays — arrives as ordinary parameters bound to its `file_variable`s and is consumed by `faq` nodes downstream; it needs no special descriptor. Scientific role (emissions, meteorology, elevation, ...) is not schema-validated and belongs in metadata.tags."
},
"source": {
"$ref": "#/$defs/DataSourceLocation"
},
"temporal": {
"$ref": "#/$defs/DataSourceTemporal"
},
"determinism": {
"$ref": "#/$defs/DataSourceDeterminism"
},
"reader_options": {
"type": "object",
"description": "Format-specific DECODE options, passed through to the format reader verbatim (EarthSciIO calls them `reader_kwargs`): the zip `member_glob` and `skip_header_row` of an FF10 inventory, a GeoTIFF band naming, and so on. They say how bytes become an array, never what the array means — no remap, no unit conversion, no filtering (those are `variables`, `unit_conversion` and `record_filter`). A key the bound reader does not recognise MUST be an error, so a mis-spelled option cannot silently decode something else.",
"additionalProperties": true
},
"select": {
"$ref": "#/$defs/DataSourceSelect"
},
"record_filter": {
"$ref": "#/$defs/DataSourceRecordFilter"
},
"extent": {
"$ref": "#/$defs/DataSourceExtent"
},
"reference": {
"$ref": "#/$defs/Reference"
},
"metadata": {
"type": "object",
"description": "Free-form metadata about the data source. The \"tags\" field (array of strings) is conventional for expressing scientific role (e.g. \"emissions\", \"reanalysis\") and is not schema-validated.",
"additionalProperties": true,
"properties": {
"tags": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
},
"EnumDeclaration": {
"type": "object",
"description": "A file-local enum mapping symbolic names to integers (esm-spec.md §9.3). The value domain is the WHOLE integer range — negative, zero and positive — because an enum member is a categorical CODE, not a position: it lowers to a `const` NUMBER used in arithmetic and in `join.on` key comparisons, where 0 and -1 are ordinary values (a source table's `opModeID = 0` or `polProcessID = -1` is a real code, not an absence). The two 1-based constructs in the format — `index`-op / index-set coordinates and `makearray` regions — are separate and carry their own bounds validation; using an enum member as an `index` argument is an authoring choice the index op bounds-checks, not a constraint on this block. Within a single enum, integer values MUST be unique. Across enums, values MAY collide (each enum is its own namespace). Bindings resolve enum-op nodes at load time before evaluating expressions.",
"minProperties": 1,
"additionalProperties": {
"type": "integer"
}
},
"TranslateTarget": {
"description": "Translation target: a simple variable reference string or an object with var and factor.",
"oneOf": [
{
"type": "string"
},
{
"type": "object",
"required": [
"var"
],
"additionalProperties": false,
"properties": {
"var": {
"type": "string"
},
"factor": {
"type": "number"
}
}
}
]
},
"ConnectorEquation": {
"type": "object",
"description": "A single equation in a ConnectorSystem linking two coupled systems.",
"required": [
"from",
"to",
"transform"
],
"additionalProperties": false,
"properties": {
"from": {
"type": "string",
"description": "Source variable (scoped reference)."
},
"to": {
"type": "string",
"description": "Target variable (scoped reference)."
},
"transform": {
"type": "string",
"enum": [
"additive",
"multiplicative",
"replacement"
],
"description": "How the expression modifies the target."
},
"expression": {
"$ref": "#/$defs/Expression",
"description": "The coupling expression."
}
}
},
"CouplingEntry": {
"description": "A single coupling rule connecting models or reaction systems. A `data_sources` entry is not a component and cannot appear as a coupling endpoint; external data enters through a parameter's `update`.",
"oneOf": [
{
"$ref": "#/$defs/CouplingOperatorCompose"
},
{
"$ref": "#/$defs/CouplingCouple"
},
{
"$ref": "#/$defs/CouplingVariableMap"
},
{
"$ref": "#/$defs/CouplingCallback"
},
{
"$ref": "#/$defs/CouplingEvent"
},
{
"$ref": "#/$defs/CouplingImport"
}
]
},
"CouplingImport": {
"type": "object",
"description": "Reuse of a coupling-library file (esm-spec §10.9, §10.10): imports the library named by `ref` and binds each of its declared roles to a component in the assembly. Expands at flatten into concrete variable_map/couple/operator_compose/event edges by substituting bound actuals for role names; the entry itself round-trips intact. Carries no `expression_template_imports` (injection is a property of the wiring entries, not of an import indirection).",
"additionalProperties": false,
"required": [
"type",
"ref"
],
"properties": {
"type": {
"const": "coupling_import"
},
"ref": {
"type": "string",
"description": "§4.7 reference (relative path, absolute path, URL, or ${VAR}) to a coupling-library file (a document with top-level `coupling_roles`)."
},
"bind": {
"type": "object",
"description": "Total map from every library role name to a scoped component reference in the assembly (esm-spec §10.10.1). Each value names a top-level or nested models/reaction_systems component (a system node), not a variable. No role may be omitted; there is no auto-binding.",
"additionalProperties": {
"type": "string"
}
},
"description": {
"type": "string"
}
}
},
"CouplingOperatorCompose": {
"type": "object",
"description": "Match LHS time derivatives and add RHS terms together.",
"required": [
"type",
"systems"
],
"additionalProperties": false,
"properties": {
"type": {
"const": "operator_compose"
},
"systems": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 2,
"maxItems": 2,
"description": "The two systems to compose."
},
"translate": {
"type": "object",
"description": "Variable mappings when LHS variables don't have matching names.",
"additionalProperties": {
"$ref": "#/$defs/TranslateTarget"
}
},
"require_match": {
"type": "boolean",
"description": "The entry's MERGE INTENT (esm-libraries-spec §4.7.1 step 5). TRI-STATE: absent is NOT the same as `false`, which is why this property declares no default. ABSENT — the author has not said; an entry that merges NOTHING is then `operator_compose_no_merge`, a hard refusal at flatten (such an entry is indistinguishable from one that is not there: the operator would integrate a private decoupled system from its own defaults and the other system would receive no contribution), while a PARTIAL merge is a warning. `true` — the `systems[1]` equations are CONTRIBUTIONS and every one of them whose LHS names a dependent variable MUST match an equation of `systems[0]`; any shortfall, PARTIAL included, is `operator_compose_require_match_unmatched`. There is no 'some is enough' reading. `false` — a standalone-contributing operator, DECLARED: unmatched equations are expected, are preserved per step 5, and nothing is reported."
},
"lifting": {
"type": "string",
"enum": [
"pointwise",
"broadcast",
"mean",
"integral"
],
"description": "Strategy for mapping between 0D and spatial systems."
},
"expression_template_imports": {
"type": "object",
"description": "Map from a target system referenced by this coupling entry to the template-library imports registered into THAT component's template scope (esm-spec §9.7.10) — assembler-chosen discretization for a PDE component as it is wired into the assembly. Each key MUST name a model/reaction-system this entry references (template_inject_target_unknown otherwise); a key resolving to neither a model nor a reaction system is template_inject_target_not_component -- which from 1.0.0 is also how a key naming a `data_sources` entry is reported, since a data source is not a component and the separate template_inject_target_is_loader code is retired. Values use the §9.7.2 entry shape. Load-time only; consumed by the §9.6.3 fixpoint; does not survive parse→emit.",
"additionalProperties": {
"type": "array",
"items": {
"$ref": "#/$defs/TemplateImport"
}
}
},
"description": {
"type": "string"
}
}
},
"CouplingCouple": {
"type": "object",
"description": "Bi-directional coupling via explicit ConnectorSystem equations.",
"required": [
"type",
"systems",
"connector"
],
"additionalProperties": false,
"properties": {
"type": {
"const": "couple"
},
"systems": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 2,
"maxItems": 2
},
"connector": {
"type": "object",
"required": [
"equations"
],
"additionalProperties": false,
"properties": {
"equations": {
"type": "array",
"items": {
"$ref": "#/$defs/ConnectorEquation"
},
"minItems": 1
}
}
},
"lifting": {
"type": "string",
"enum": [
"pointwise",
"broadcast",
"mean",
"integral"
],
"description": "Strategy for mapping between 0D and spatial systems."
},
"expression_template_imports": {
"type": "object",
"description": "Map from a target system referenced by this coupling entry to the template-library imports registered into THAT component's template scope (esm-spec §9.7.10) — assembler-chosen discretization for a PDE component as it is wired into the assembly. Each key MUST name a model/reaction-system this entry references (template_inject_target_unknown otherwise); a key resolving to neither a model nor a reaction system is template_inject_target_not_component -- which from 1.0.0 is also how a key naming a `data_sources` entry is reported, since a data source is not a component and the separate template_inject_target_is_loader code is retired. Values use the §9.7.2 entry shape. Load-time only; consumed by the §9.6.3 fixpoint; does not survive parse→emit.",
"additionalProperties": {
"type": "array",
"items": {
"$ref": "#/$defs/TemplateImport"
}
}
},
"description": {
"type": "string"
}
}
},
"CouplingVariableMap": {
"type": "object",
"description": "Replace a parameter in one system with a variable from another.",
"required": [
"type",
"from",
"to",
"transform"
],
"additionalProperties": false,
"properties": {
"type": {
"const": "variable_map"
},
"from": {
"type": "string",
"description": "Source variable (scoped reference, e.g., \"GEOSFP.T\")."
},
"to": {
"type": "string",
"description": "Target parameter (scoped reference, e.g., \"SuperFast.T\")."
},
"transform": {
"oneOf": [
{
"type": "string",
"enum": [
"param_to_var",
"identity",
"additive",
"multiplicative",
"conversion_factor"
]
},
{
"$ref": "#/$defs/ExpressionNode"
}
],
"description": "How the mapping is applied: one of the named transforms, or an Expression evaluated on the source value(s) in the flattened coupled system's scope (spec §8.6/§10.4/§10.5 — the regridding form; the expression must reference the entry's `from` variable via a fully-scoped reference and may reference any other in-scope variable, e.g. build-once overlap weights in the receiving component; `apply_expression_template` invocations are legal and resolve at load per §9.6.4 — eager references expand, the rest survive and denote their expansion). The Expression form is an operator node: the degenerate bare-reference and literal Expression spellings are not admissible here (the named string transforms already cover bare replacement, and the string space is reserved for them)."
},
"factor": {
"type": "number",
"description": "Scaling coefficient applied by a scaling transform (additive, multiplicative, conversion_factor). Not permitted with param_to_var, identity, or an Expression transform, which replace/assign/compute without a separate scaling slot."
},
"lifting": {
"type": "string",
"enum": [
"pointwise",
"broadcast",
"mean",
"integral"
],
"description": "Strategy for mapping between 0D and spatial systems."
},
"expression_template_imports": {
"type": "object",
"description": "Map from a target system referenced by this coupling entry to the template-library imports registered into THAT component's template scope (esm-spec §9.7.10) — assembler-chosen discretization for a PDE component as it is wired into the assembly. Each key MUST name a model/reaction-system this entry references (template_inject_target_unknown otherwise; the `variable_map` reference fields are `from`/`to`); a key resolving to neither a model nor a reaction system is template_inject_target_not_component -- which from 1.0.0 is also how a key naming a `data_sources` entry is reported, since a data source is not a component and the separate template_inject_target_is_loader code is retired. Values use the §9.7.2 entry shape. Load-time only; consumed by the §9.6.3 fixpoint; does not survive parse→emit.",
"additionalProperties": {
"type": "array",
"items": {
"$ref": "#/$defs/TemplateImport"
}
}
},
"description": {
"type": "string"
}
},
"allOf": [
{
"$comment": "`factor` scales the coupling, so it is only valid with a scaling transform (additive, multiplicative, conversion_factor). A bare replace (param_to_var) or assign (identity) has nothing to scale, and an Expression transform spells its own arithmetic (fold scaling into the expression), so a `factor` alongside any of those is a modeling error and is rejected rather than silently ignored. The enum constraint below enforces this: a non-enum (Expression) transform fails it whenever `factor` is present.",
"if": {
"required": [
"factor"
]
},
"then": {
"properties": {
"transform": {
"enum": [
"additive",
"multiplicative",
"conversion_factor"
]
}
}
}
}
]
},
"CouplingCallback": {
"type": "object",
"description": "Register a callback for simulation events.",
"required": [
"type",
"callback_id"
],
"additionalProperties": false,
"properties": {
"type": {
"const": "callback"
},
"callback_id": {
"type": "string",
"description": "Registered identifier for the callback."
},
"config": {
"type": "object",
"additionalProperties": true
},
"expression_template_imports": {
"type": "object",
"description": "Map from a target system referenced by this coupling entry to the template-library imports registered into THAT component's template scope (esm-spec §9.7.10) — assembler-chosen discretization for a PDE component as it is wired into the assembly. Each key MUST name a model/reaction-system this entry references (template_inject_target_unknown otherwise); a key resolving to neither a model nor a reaction system is template_inject_target_not_component -- which from 1.0.0 is also how a key naming a `data_sources` entry is reported, since a data source is not a component and the separate template_inject_target_is_loader code is retired. Values use the §9.7.2 entry shape. Load-time only; consumed by the §9.6.3 fixpoint; does not survive parse→emit.",
"additionalProperties": {
"type": "array",
"items": {
"$ref": "#/$defs/TemplateImport"
}
}
},
"description": {
"type": "string"
}
}
},
"CouplingEvent": {
"type": "object",
"description": "Cross-system event involving variables from multiple coupled systems.",
"required": [
"type",
"event_type",
"affects"
],
"additionalProperties": false,
"properties": {
"type": {
"const": "event"
},
"event_type": {
"type": "string",
"enum": [
"continuous",
"discrete"
],
"description": "Whether this is a continuous or discrete event."
},
"name": {
"type": "string",
"description": "Human-readable identifier."
},
"conditions": {
"type": "array",
"items": {
"$ref": "#/$defs/Expression"
},
"description": "Condition expressions (zero-crossing for continuous, boolean for discrete)."
},
"trigger": {
"$ref": "#/$defs/DiscreteEventTrigger",
"description": "Trigger specification (for discrete events)."
},
"affects": {
"type": "array",
"items": {
"$ref": "#/$defs/AffectEquation"
},
"description": "Affect equations. Required: esm 1.0.0 removed the `functional_affect` alternative, so `affects` is the only affect channel. Every LHS MUST name an unknown (`event_affects_parameter` otherwise)."
},
"affect_neg": {
"oneOf": [
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/AffectEquation"
}
}
]
},
"root_find": {
"type": "string",
"enum": [
"left",
"right"
]
},
"reinitialize": {
"type": "boolean"
},
"expression_template_imports": {
"type": "object",
"description": "Map from a target system referenced by this coupling entry to the template-library imports registered into THAT component's template scope (esm-spec §9.7.10) — assembler-chosen discretization for a PDE component as it is wired into the assembly. Each key MUST name a model/reaction-system this entry references (template_inject_target_unknown otherwise); a key resolving to neither a model nor a reaction system is template_inject_target_not_component -- which from 1.0.0 is also how a key naming a `data_sources` entry is reported, since a data source is not a component and the separate template_inject_target_is_loader code is retired. Values use the §9.7.2 entry shape. Load-time only; consumed by the §9.6.3 fixpoint; does not survive parse→emit.",
"additionalProperties": {
"type": "array",
"items": {
"$ref": "#/$defs/TemplateImport"
}
}
},
"description": {
"type": "string"
}
},
"allOf": [
{
"if": {
"properties": {
"event_type": {
"const": "continuous"
}
}
},
"then": {
"required": [
"conditions"
]
}
},
{
"if": {
"properties": {
"event_type": {
"const": "discrete"
}
}
},
"then": {
"required": [
"trigger"
]
}
}
]
},
"Coordinate": {
"type": "object",
"description": "One entry of the document-scoped `coordinates` registry (RFC streaming-output-sinks §8): marks an existing data array (or an inline literal vector) as a physical coordinate and attaches CF metadata. Exactly one of `source` (reference an existing array by name) or `values` (inline literal) MUST be present. The coordinate's shape/dimensions come from its source, so no per-axis attachment is needed; the writer resolves CF role (dimension vs auxiliary) from that shape.",
"additionalProperties": false,
"oneOf": [
{
"required": [
"source"
]
},
{
"required": [
"values"
]
}
],
"properties": {
"source": {
"type": "string",
"description": "Name of an existing data array — a model unknown or parameter (including one fed from a `data_sources` entry) — supplying this coordinate's values. Referenced by name exactly as a ragged `IndexSet` references its `offsets`/`values` factors. Mutually exclusive with `values`. The array's declared shape (its ordered index-set dimensions) IS the coordinate's shape: 1-D monotonic over a grid axis → CF dimension coordinate; 1-D over a shared dimension (e.g. `lat(cells)`) or 2-D (`lat(y,x)`) → CF auxiliary coordinate."
},
"values": {
"type": "array",
"description": "Inline literal 1-D coordinate vector for the simple rectilinear case, mirroring `FunctionTableAxis.values` (finite floats). Mutually exclusive with `source`. Use `source` for anything not a plain 1-D literal (unstructured/curvilinear coordinates live in data arrays).",
"items": {
"type": "number"
},
"minItems": 1
},
"standard_name": {
"type": "string",
"description": "CF standard name (e.g. \"latitude\", \"longitude\", \"air_pressure\"). Emitted verbatim as the coordinate variable's `standard_name` attribute."
},
"units": {
"type": "string",
"description": "CF/UDUNITS units string (e.g. \"degrees_north\", \"degrees_east\", \"Pa\"). Emitted as the coordinate variable's `units` attribute. Advisory at load time (no unit checking), matching `FunctionTableAxis.units`."
},
"axis": {
"type": "string",
"description": "Optional CF axis role for a rectilinear dimension coordinate. Set it ONLY for a 1-D monotonic dimension coordinate; omit it for auxiliary coordinates (unstructured/curvilinear), which have no single axis. Emitted as the `axis` attribute.",
"enum": [
"X",
"Y",
"Z",
"T"
]
}
}
},
"IndexSet": {
"type": "object",
"description": "A named index set (RFC semiring-faq-unified-ir §5.2): the declaration shape for an iteration domain referenced from a `faq` range via { \"from\": <name> }. Covers grid axes and categorical dimensions under one shape. Exactly one of four kinds, each requiring its own fields.",
"required": [
"kind"
],
"additionalProperties": false,
"properties": {
"kind": {
"type": "string",
"description": "Which of the four index-set forms this entry is. \"interval\": a dense [1..size] grid axis. \"categorical\": an explicit enumeration of members. \"derived\": a data-derived set materialized from an index-set-producing node (a `distinct` `faq`, or an `intersect_polygon` ring leaf whose clipped ring has a data-dependent vertex count, §8.1). \"ragged\": a per-parent (dependent) inner set backed by an `offsets` per-parent length factor and a padded `values` member factor; a `faq` range over it binds the POSITION k in 1…offsets[parent] (esm-spec §4.3.1 \"Ragged ranges\").",
"enum": [
"interval",
"categorical",
"derived",
"ragged"
]
},
"size": {
"description": "interval: number of members in the dense interval (the grid-axis length). Required when kind is \"interval\". MAY be a metaparameter expression folded to a concrete integer at load (esm-spec §9.7.6).",
"$ref": "#/$defs/MetaparameterExpression"
},
"members": {
"type": "array",
"description": "categorical: the explicit enumeration of members (e.g. county FIPS codes, fuel types). Required when kind is \"categorical\"."
},
"from_faq": {
"type": "string",
"description": "derived: the id of the index-set-producing node (RFC §5.5) that materializes this set, named by its `id`. Usually a `faq` node (`distinct: true`) — e.g. the unique edges discovered from a face→vertex relation. It MAY also be an `intersect_polygon` geometry-kernel leaf (RFC §8.1): the clipped overlap ring it returns has a data-dependent number of vertices, so the ring's vertex set is exactly such a derived index set, and `polygon_area` is then an ordinary `sum_product` FAQ over it. Required when kind is \"derived\"."
},
"member_factor": {
"type": "string",
"description": "derived: name of the buffer that receives the surviving member key per invented position (CONFORMANCE_SPEC §5.5, Hook 1) — fed back as a `const` factor so a `faq` ranging over the compact derived axis can gather the full-grid rows that axis selects. That is what downstream FAQ nodes do; it is not a claim about ORIENTATION — a `faq` that reduces OVER the compact axis, and one whose overlap-gate envelope factors are themselves such gathers, gather exactly the same way (CONFORMANCE_SPEC §5.5.7). OPTIONAL, and only meaningful when kind is \"derived\" and `from_faq` names an overlap-gated `distinct` `faq`. Pairs with a provider axis marked `gated_by: \"<this set>\"`, which is DEFERRED past value-invention and then fetched with a Selection built from the materialised members in sorted order (the `gated_select` pushdown)."
},
"of": {
"type": "array",
"description": "ragged: the parent index-set name(s) this inner set depends on (e.g. [\"cells\"] for the edges of each cell). Required when kind is \"ragged\".",
"items": {
"type": "string"
}
},
"offsets": {
"type": "string",
"description": "ragged: name of the keyed factor giving |set(i)| for each parent tuple — the per-parent LENGTH, not a cumulative offset (e.g. MPAS nEdgesOnCell). A `faq` range {\"from\": <this set>, \"of\": [\"i\"]} binds the POSITION k in 1…offsets[i] (esm-spec §4.3.1 \"Ragged ranges\"). Required when kind is \"ragged\"."
},
"values": {
"type": "string",
"description": "ragged: name of the keyed factor giving the member at (i, k) for k in 1…|set(i)| — a PADDED [parent, max length] array whose row i holds parent i's members in positions 1…offsets[i] (e.g. MPAS edgesOnCell); entries past offsets[i] are padding and are never read. Because a range over the set binds the position k, a `faq` body reads a member by gathering it explicitly, index(values, i, k); a body that never reads this array is `ragged_values_not_gathered`. The one exception is a value-invention `faq` (distinct / skolem / rank / argmin / argmax), whose ragged range binds the member values[i, k] itself (esm-spec §4.3.1 \"Ragged ranges\"). Required when kind is \"ragged\"."
}
},
"allOf": [
{
"if": {
"properties": {
"kind": {
"const": "interval"
}
},
"required": [
"kind"
]
},
"then": {
"required": [
"size"
]
}
},
{
"if": {
"properties": {
"kind": {
"const": "categorical"
}
},
"required": [
"kind"
]
},
"then": {
"required": [
"members"
]
}
},
{
"if": {
"properties": {
"kind": {
"const": "derived"
}
},
"required": [
"kind"
]
},
"then": {
"required": [
"from_faq"
]
}
},
{
"if": {
"properties": {
"kind": {
"const": "ragged"
}
},
"required": [
"kind"
]
},
"then": {
"required": [
"of",
"offsets",
"values"
]
}
}
]
},
"Domain": {
"type": "object",
"description": "Spatiotemporal domain specification (DomainInfo).",
"additionalProperties": false,
"properties": {
"independent_variable": {
"type": "string",
"description": "Name of the independent (time) variable.",
"default": "t"
},
"temporal": {
"type": "object",
"additionalProperties": false,
"properties": {
"start": {
"type": "string",
"format": "date-time"
},
"end": {
"type": "string",
"format": "date-time"
},
"reference_time": {
"type": "string",
"format": "date-time"
}
}
},
"element_type": {
"type": "string",
"enum": [
"Float32",
"Float64"
],
"description": "Floating point precision.",
"default": "Float64"
},
"array_type": {
"type": "string",
"description": "Array backend (e.g., \"Array\", \"CuArray\").",
"default": "Array"
}
}
},
"FunctionTable": {
"type": "object",
"description": "A sampled function table (esm-spec.md §9.5). Carries one or more named axes and a literal nested-array data block. The shape of `data` is [len(outputs), len(axes[0].values), len(axes[1].values), ...] when `outputs` is declared; otherwise [len(axes[0].values), ...] (single-output convenience form). `table_lookup` AST nodes evaluate this table by supplying a per-axis input expression and selecting an output. Tables are syntactic sugar over `interp.linear` (1 axis) / `interp.bilinear` (2 axes) / `index` (nearest); the materialized AST a binding produces from a `table_lookup` MUST be bit-equivalent to the equivalent inline-const lookup.",
"required": [
"axes",
"data"
],
"additionalProperties": false,
"properties": {
"description": {
"type": "string"
},
"axes": {
"type": "array",
"description": "Ordered list of named axes. The order of entries defines the order of inner dimensions in `data` (after the leading output dimension when `outputs` is present). Axis names within a single table MUST be unique.",
"items": {
"$ref": "#/$defs/FunctionTableAxis"
},
"minItems": 1,
"maxItems": 2
},
"interpolation": {
"type": "string",
"description": "Interpolation kind applied by `table_lookup`. 'linear' (1 axis) lowers to `interp.linear`. 'bilinear' (2 axes) lowers to `interp.bilinear`. 'nearest' lowers to `index` after `interp.searchsorted`. The chosen kind MUST be consistent with the number of axes; mismatch is rejected at load time with diagnostic 'table_interpolation_axes_mismatch'.",
"enum": [
"linear",
"bilinear",
"nearest"
],
"default": "linear"
},
"out_of_bounds": {
"type": "string",
"description": "Out-of-bounds policy applied to query coordinates that fall outside an axis range. 'clamp' pins to the nearest edge — this matches the semantics of `interp.linear` and `interp.bilinear` (extrapolate-flat). 'error' MUST raise at evaluation time; bindings emit diagnostic 'table_lookup_out_of_bounds' on first violation. v0.4.0: 'clamp' is the only policy required of all five bindings; 'error' is conformant when the binding implements it.",
"enum": [
"clamp",
"error"
],
"default": "clamp"
},
"outputs": {
"type": "array",
"description": "Optional ordered list of output names. When present, `table_lookup.output` MAY name an entry of this list (in addition to using a 0-based integer index). Names within a table MUST be unique. The leading dimension of `data` MUST equal the length of `outputs`.",
"items": {
"type": "string"
},
"minItems": 1
},
"data": {
"description": "Nested-array literal carrying the table's sampled values. Leaves MUST be finite numbers (NaN entries are rejected at load time with 'table_data_nan'). Shape: [len(outputs), len(axes[0].values), ...] when `outputs` is present; [len(axes[0].values), ...] otherwise. Mismatched nesting is rejected with 'table_data_shape_mismatch'."
},
"shape": {
"type": "array",
"description": "Optional redundant shape assertion. If present, MUST match the actual nesting of `data`; loaders verify and reject mismatches with 'table_data_shape_mismatch'. `data` is the canonical representation; `shape` is a load-time assertion only.",
"items": {
"type": "integer",
"minimum": 1
},
"minItems": 1
},
"schema_version": {
"type": "string",
"description": "Optional pin of the table-schema minor version this entry was authored against. Bindings ignore the value beyond a same-major-version compatibility check; informational for tooling.",
"pattern": "^\\d+\\.\\d+\\.\\d+$"
}
}
},
"FunctionTableAxis": {
"type": "object",
"description": "A single named axis inside a FunctionTable. The `values` array supplies the sample coordinates along this axis; it MUST be strictly increasing finite floats with at least 2 entries (mirrors the `interp.linear` / `interp.bilinear` axis contract in §9.2).",
"required": [
"name",
"values"
],
"additionalProperties": false,
"properties": {
"name": {
"type": "string",
"description": "Axis identifier. Used as the key in `table_lookup.axes` to bind the input-coordinate expression."
},
"units": {
"type": "string",
"description": "Optional advisory units string (e.g. 'Pa', 'K'). v0.4.0 records this for documentation only — no load-time unit checking is performed against the supplied input expression. Promotion to enforcement is deferred to a future units RFC."
},
"values": {
"type": "array",
"description": "Strictly-increasing finite floats. Bindings MUST reject non-monotonic axes at load time with diagnostic 'table_axis_non_monotonic' and NaN entries with 'table_axis_nan'.",
"items": {
"type": "number"
},
"minItems": 2
}
}
}
}
}