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 JSON Schema for a YAML file
{
  "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
}
still a string
service.novs a NOVA schema
@schema service@1.0.0
@root Service

record Service:
  id: string
  port: u16 @range(1..65535)
  replicas: u16 @range(0..100) = 2
  deployed_at?: timestamp
name and SemVer version
type of the document
closed by default
default
a real timestamp

With 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

Topictyped YAMLNOVASpec
Schema languageJSON Schema, written in JSON or YAMLA small .novs language with records, enums and aliases§6.1
Types from the schemaValidation only; a date stays a stringResolution turns strings into timestamps, durations, decimals and enums§6.3
Unknown fieldsAllowed unless additionalProperties: falseRejected unless the record is @open§6.1
ErrorsDepends on the validatorEvery violation, each with its path§6.4
Enums with dataoneOf with a discriminator fieldenum Status = active | failed(string)§2.11
VersionsA $id by conventionSemVer, 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.novs
service.nova two mistakes
@schema service@1.0.0

id: api
port: 70000
replicas: two
deployed_at: 2026-11-17T16:00:00Z
All 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 string

The 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.