JSON Schemas

The following JSON Schema files describe the structure of each JSON input file in a Cobre case directory. Point your editor’s JSON Schema validation setting at the appropriate file to get autocompletion, hover documentation, and inline error highlighting while authoring case inputs.

For a complete description of each file’s fields and validation rules, see the Case Directory Format reference page.

operational_start_date

Every system/* entity registry schema (buses, hydros, thermals, lines, non-controllable sources, pumping stations, energy contracts) requires an operational_start_date field — an ISO-8601 calendar date (YYYY-MM-DD). It is provenance and the canonical (operational_start_date, id) ordering key only; see Notation Conventions and Case Directory Format for field-level detail.

Available schemas

Schema file	Input file	Description
config.schema.json	config.json	Study configuration: training parameters, stopping rules, cut selection, simulation settings, and export flags
penalties.schema.json	penalties.json	Global penalty cost defaults for bus deficit, line exchange, hydro violations, and non-controllable source curtailment
stages.schema.json	stages.json	Temporal structure of the study: stage sequence, load blocks, and policy graph horizon
buses.schema.json	system/buses.json	Electrical bus registry: bus identifiers, names, and optional entity-level deficit cost tiers
lines.schema.json	system/lines.json	Transmission line registry: line identifiers, source/target buses, and directional MW capacity bounds
hydros.schema.json	system/hydros.json	Hydro plant registry: reservoir bounds, outflow limits, generation model parameters, and cascade linkage
thermals.schema.json	system/thermals.json	Thermal plant registry: generation bounds and linear cost coefficients
energy_contracts.schema.json	system/energy_contracts.json	Bilateral energy contract registry (optional entities)
non_controllable_sources.schema.json	system/non_controllable_sources.json	Intermittent (non-dispatchable) generation source registry (optional entities)
pumping_stations.schema.json	system/pumping_stations.json	Pumping station registry (optional entities)
production_models.schema.json	system/hydro_production_models.json	Production model selection, FPHA hyperplane config, and per-stage productivity overrides (optional)
scalar_parameters.schema.json	system/scalar_parameters.json	Named scalar study parameters (single-valued numeric settings)
initial_conditions.schema.json	initial_conditions.json	Initial reservoir storage, past inflows for PAR lag initialization
correlation.schema.json	scenarios/correlation.json	Inter-site correlation matrix for scenario generation (supports inflow, load, and NCS entity types)
generic_constraints.schema.json	constraints/generic_constraints.json	User-defined linear constraints over LP variables with optional slack penalties
exchange_factors.schema.json	constraints/exchange_factors.json	Block-level line capacity multipliers for directional exchange limits
load_factors.schema.json	scenarios/load_factors.json	Block-level load scaling factors for bus-stage demand profiles
non_controllable_factors.schema.json	scenarios/non_controllable_factors.json	Block-level NCS availability scaling factors per source per stage per block

Using schemas in your editor

Every schema is served straight from this site at a stable, versioned-free URL: /schemas/<name>.schema.json (for example https://docs.cobre-rs.dev/schemas/config.schema.json once the site is live at that domain). Point your editor’s JSON Schema mapping there for autocompletion and validation while authoring case inputs.

VS Code

Add a json.schemas entry to your workspace .vscode/settings.json:

{
  "json.schemas": [
    {
      "fileMatch": ["config.json"],
      "url": "https://docs.cobre-rs.dev/schemas/config.schema.json"
    },
    {
      "fileMatch": ["system/hydros.json"],
      "url": "https://docs.cobre-rs.dev/schemas/hydros.schema.json"
    }
  ]
}

Alternatively, add a $schema key directly inside each JSON file:

{
  "$schema": "https://docs.cobre-rs.dev/schemas/config.schema.json",
  "training": {
    "forward_passes": 192,
    "stopping_rules": [{ "type": "iteration_limit", "limit": 200 }]
  }
}

Neovim (via jsonls)

Configure json.schemas in your nvim-lspconfig setup for jsonls following the same URL pattern shown above.

JetBrains IDEs

Go to Preferences > Languages & Frameworks > Schemas and DTDs > JSON Schema Mappings, add a new mapping, paste the schema URL, and select the file pattern.

Before the site is live

Until docs.cobre-rs.dev is serving this site, the identical schema content is also available straight from the tagged cobre repository, e.g. https://raw.githubusercontent.com/cobre-rs/cobre/v0.10.0/book/src/schemas/config.schema.json.

Provenance and refreshing

These schemas are generated in the cobre repository from the cobre-io Rust types — the Rust types are the ground truth, and the schema files are their generated output, licensed Apache-2.0. This site vendors a committed copy (currently at the v0.10.0 tag) under public/schemas/ so the files have a stable URL to serve from and to link to.

Do not hand-edit any vendored schema file. When cobre regenerates the schemas (after a change to a cobre-io input type), re-vendor the committed copy here with:

npm run refresh:schemas

Run npm run refresh:schemas -- --check to verify the committed copy still matches the source tag without writing anything.