Schema revision

Every OpenTide object carries two version-like fields, and mixing them up is the single most common authoring mistake. This page explains what each controls and why they are separate.

Two fields, two jobs

• metadata.schema — the structural schema revision. It selects the validation model and the generated rule.1.0.schema.json your editor and CLI check against. It changes only when the shape of the object changes (new required fields, renamed structures), which is rare and governed by the specifications.
• metadata.version — the instance content version. It is your semver-style marker for how a specific detection has evolved. Bump it when you meaningfully change the rule's logic. The real, line-by-line history lives in git.

Naming conventions

The schema identifier maps predictably to files and specs:

Your editor validates YAML live because the IDE router reads each file's metadata.schema and applies the matching JSON Schema — no per-file configuration required.

How revisions coexist

Schema revisions are additive. When a new revision such as rule::1.1 ships, both revisions can exist in the same repo at once:

1. opentide generate schemas emits both rule.1.0.schema.json and rule.1.1.schema.json.
2. The IDE router adds a branch for each identifier and routes objects by their declared metadata.schema.
3. Objects opt in individually by setting metadata.schema: rule::1.1. Objects that still declare rule::1.0 keep validating against 1.0 until you migrate them.

This means a schema upgrade never forces a big-bang migration — you move objects over at your own pace. For CoreTide-era repos, see the migration guide.

What to do when

Normative reference

• Versioning spec — the rules for how revisions are numbered and deprecated.
• Metadata spec — the full metadata field contract.