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:

The router opentide.schema.json is the editor entry point. opentide setup vscode maps objects/**/*.yaml to it, and the router applies the revision schema named in each object's metadata.schema:

• metadata.schema completes to the registered object identifiers (objective::1.0, rule::1.0, rule::1.1, threat::1.0). An unknown identifier is reported on that field with the valid values.
• Each identifier has one if/then branch, combined with allOf. Only the branch whose identifier matches applies, so a rule::1.1 object is checked against rule.1.1.schema.json and nothing else.
• Branches reference the revision schemas by relative file name, so they resolve to the files next to the router in .opentide/schemas/.

Map the router, not a revision schema. A folder mapping such as objects/rules/**/*.yaml → rule.1.0.schema.json checks every rule against rule::1.0 and flags valid rule::1.1 objects.

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 and a metadata.schema value 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.

rule::1.1 is that kind of revision. It adds optional metadata.reviewed and changes nothing else. rule::1.0 stays valid and rejects the field. opentide generate schemas writes both rule.1.0.schema.json and rule.1.1.schema.json. opentide generate templates writes both templates and leaves reviewed commented out, so a new file does not invent a review date. List stale rules with opentide rules unreviewed.

What to do when

Normative reference

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