feat: add schemas/vspec-node.schema.json — machine-readable vspec node format#920
Open
SoundMatt wants to merge 1 commit into
Open
feat: add schemas/vspec-node.schema.json — machine-readable vspec node format#920SoundMatt wants to merge 1 commit into
SoundMatt wants to merge 1 commit into
Conversation
The vspec YAML node format is currently documented only by example and by
the Python toolchain's parser. Third-party tooling authors must reverse-
engineer the field set and silently drop unknown fields when the spec adds
new ones.
Add schemas/vspec-node.schema.json (JSON Schema 2020-12) describing the
structure of a single vspec node:
required: type (enum: branch|sensor|actuator|attribute)
optional: datatype, description, unit, min, max, default, comment,
deprecation, instances, allowed, pattern
constraint: additionalProperties: false
The additionalProperties: false constraint makes this schema normative
rather than just descriptive: any new field added to the spec without
updating the schema becomes a visible, reviewable diff.
Update README.md with a one-paragraph note so tooling authors can find it.
Signed-off-by: Matt Jones <matt@jellybaby.com>
Signed-off-by: Matt Jones <47545907+SoundMatt@users.noreply.github.com>
sschleemilch
reviewed
Jun 9, 2026
Collaborator
There was a problem hiding this comment.
I believe vss-tools could (and should) generate it since we are using pydantic and is then the single source of truth aligned.
Basically VSSData.model_json_schema() and VSSDataDatatype.model_json_schema().
Sure, it also contains internal things and probably needs to be tuned a bit
| "description": "Unit of measure. Should be a value from the VSS unit catalogue (spec/units.yaml)." | ||
| }, | ||
| "min": { | ||
| "description": "Minimum valid value (numeric). Applies to leaf nodes only." |
| "description": "Minimum valid value (numeric). Applies to leaf nodes only." | ||
| }, | ||
| "max": { | ||
| "description": "Maximum valid value (numeric). Applies to leaf nodes only." |
| }, | ||
| "allowed": { | ||
| "type": "array", | ||
| "description": "Enumerated allowed values for the signal. Items should match the datatype.", |
Collaborator
There was a problem hiding this comment.
Suggested change
| "description": "Enumerated allowed values for the signal. Items should match the datatype.", | |
| "description": "Enumerated allowed values for the signal. Items must match the datatype.", |
| "pattern": { | ||
| "type": "string", | ||
| "description": "Regular expression that the signal value must match." | ||
| } |
Collaborator
|
Thanks for the PR. |
erikbosch
reviewed
Jun 16, 2026
|
|
||
| ### Machine-readable node schema | ||
|
|
||
| `schemas/vspec-node.schema.json` is a [JSON Schema 2020-12](https://json-schema.org/draft/2020-12/schema) document that describes every field a vspec YAML node may carry. Third-party tooling authors can validate against it so that unknown or misspelled fields are caught at parse time, and any future field additions to the spec are automatically a visible, reviewable diff to the schema. The `additionalProperties: false` constraint is intentional — it makes the schema normative rather than just descriptive. |
Collaborator
There was a problem hiding this comment.
I do not know how easy it would be to create a minimal example on how this could be used, that we potentially could execute as part of CI to verify that std catalog and the schema are in sync. I am thinking of something
vspec export yamlorvspec export json- And then some command that checks that it complies with schema
Have you done any checks like that to verify that the schema works with the current std catalog?
Collaborator
|
MoM:
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
schemas/vspec-node.schema.json— a JSON Schema 2020-12 document describing every field a vspec YAML node may carry.README.mdwith a one-paragraph note pointing to the schema.Motivation
The vspec YAML node format is currently documented only by example and by the Python toolchain's parser. Third-party tooling authors must reverse-engineer the field set and silently drop unknown fields when the spec adds new ones. A JSON Schema document gives them a stable, versioned contract to validate against.
The
additionalProperties: falseconstraint is the key part — it makes the schema normative rather than just descriptive. Any field added to the spec in the future without updating the schema becomes a visible, reviewable diff rather than a silent addition.Schema coverage
typebranch,sensor,actuator,attribute(required)datatypedescriptionunitspec/units.yamlmin/maxdefaultcommentdeprecationinstancesallowedpatternTest plan
jsonschemavalidates each of the sample vspec files against this schemaspec/are representedadditionalProperties: falsecatches unknown fields