Typed YAML: block layout and comments, with schemas built in
Typing YAML today means a JSON Schema next to the file and a validator that only says yes or no. NOVA keeps the block layout and the comments, and adds a schema language that is part of the format: it validates, reports every violation with its path, and gives values their types.
service.schema.json {
"type": "object",
"required": ["id", "port"],
"properties": {
"id": {"type": "string"},
"port": {"type": "integer", "minimum": 1, "maximum": 65535},
"replicas": {"type": "integer", "minimum": 0, "maximum": 100, "default": 2},
"deployed_at": {"type": "string", "format": "date-time"}
},
"additionalProperties": false
}service.novs @schema service@1.0.0
@root Service
record Service:
id: string
port: u16 @range(1..65535)
replicas: u16 @range(0..100) = 2
deployed_at?: timestampWith the schema, deployed_at: 2026-11-17T16:00:00Z resolves to a timestamp. Without one it stays a string, as every bare word does. Schema-directed resolution, spec §6.3
What changes
| Topic | typed YAML | NOVA | Spec |
|---|---|---|---|
| Schema language | JSON Schema, written in JSON or YAML | A small .novs language with records, enums and aliases | §6.1 |
| Types from the schema | Validation only; a date stays a string | Resolution turns strings into timestamps, durations, decimals and enums | §6.3 |
| Unknown fields | Allowed unless additionalProperties: false | Rejected unless the record is @open | §6.1 |
| Errors | Depends on the validator | Every violation, each with its path | §6.4 |
| Enums with data | oneOf with a discriminator field | enum Status = active | failed(string) | §2.11 |
| Versions | A $id by convention | SemVer, checked against the schema diff | §6.7 |
Migrating
Convert the data, import the JSON Schema you already have, then validate. The document can name its schema with @schema; parsers never fetch it.
nvf convert service.yaml --to nova -o service.nova
nvf schema from-json-schema service.schema.json > service.novs
nvf validate service.nova --schema service.novsservice.nova @schema service@1.0.0
id: api
port: 70000
replicas: two
deployed_at: 2026-11-17T16:00:00ZAll of them, at once $ nvf validate service.nova --schema service.novs
× service.nova is invalid against [email protected]#772b44744ddfe225 (3 issues)
× port: 70000 is out of range for u16
× port: 70000 is outside @range(1..65535)
× replicas: expected u16, found stringThe language server shows the same diagnostics in the editor, using the schemas in your workspace. Validation, spec §6.4
When to stay with YAML and JSON Schema
- Your tool only reads YAML, such as Kubernetes or a CI system, and your editor already validates it against a JSON Schema. Keep YAML at that boundary and generate it with
nvf convert --to yaml. - You need a format that is stable today. NOVA is a 0.1 draft, and minor versions must match exactly while the major version is 0.
Questions
Do I need a schema to use NOVA?
No. Documents without a schema are complete on their own. A schema adds types, constraints, defaults and versioning when you want them.
Can I keep my JSON Schema?
nvf schema from-json-schema converts a JSON Schema (2020-12 or draft-07) into a NOVA schema, and nvf schema json-schema goes the other way for tools that expect one.
What is checked when a schema version changes?
nvf schema check old.novs new.novs classifies each change as compatible or breaking and fails if the version bump is too small, so 1.4.0 really can read 1.2.0 data.