Schemas¶
Packaged JSON Schemas describe scenario inputs and exported results. They drive validation and IDE completion.
Where the schemas are¶
ngraph/schemas/scenario.json covers scenario inputs; ngraph/schemas/results.json covers the results file. Both ship in the installed package.
What validation checks¶
The schema checks value types, required fields, allowed keys and simple constraints such as enumerations and minimums. Unknown input keys are refused with their location.
Scenario.from_yaml always validates against the schema before expansion. Rules the schema cannot express are checked in code: blueprint parameter names, risk-group references, and unrecognized keys in sections whose schema allows additional properties, such as workflow step parameters. Every refusal is a ValueError whose message starts with the field's path and value; a schema refusal keeps the schema's ValidationError as its cause.
IDE Integration (VS Code)¶
Add to .vscode/settings.json (not committed to the repository):
{
"yaml.schemas": {
"./ngraph/schemas/scenario.json": [
"scenarios/**/*.yaml",
"scenarios/**/*.yml"
]
}
}
The YAML extension then validates and completes scenario files as you type.
Validate from Python¶
import json
import yaml
import jsonschema
# Load and validate
from importlib import resources as res
with res.files('ngraph.schemas').joinpath('scenario.json').open('r', encoding='utf-8') as f:
schema = json.load(f)
with open('scenarios/square_mesh.yaml') as f:
data = yaml.safe_load(f)
jsonschema.validate(data, schema)
Top-level sections¶
The top-level keys and what each holds are listed in Scenario YAML.
For contributors¶
ngraph/schemas/results.json and the Results page are generated by dev/generate_results_schema.py from the result record declarations (plain records and their Annotated refinements) and the explicit fragments in dev/explicit_results_schema.json. Every result field has one description, where it is declared: the attribute docstring of a record field, or the description of a fragment node; the generator refuses a field without one.
ngraph/schemas/scenario.json is maintained by hand: update it whenever a top-level section, a field's type or a workflow step type changes. The Scenario YAML and Workflow Steps pages name every scenario.json property (a test checks it).