Skip to content
OpenTrackPlan
This page describes OpenTrackPlan 2026-09. Earlier versions: 2026-01.

Schema

Schema Reference

Section titled “Schema Reference”

OpenTrackPlan uses YAML files for configuration. This section covers all file formats.

File Types

Section titled “File Types”
FilePurposeSchema
opentp.yamlMain configurationopentp.schema.json
events/*.yamlEvent definitionsevent.schema.json
dictionaries/*.yamlReusable value listsdict.schema.json

.yaml and .yml are equivalent. Payload field definitions in all files share field.schema.json.

JSON Schemas

Section titled “JSON Schemas”

All file formats have JSON schemas (JSON Schema draft-07) for IDE validation and autocompletion.

Add this comment at the top of your YAML files:

# yaml-language-server: $schema=https://opentp.dev/schemas/latest/opentp.schema.json

Schema URLs

Section titled “Schema URLs”
SchemaURL
Main confighttps://opentp.dev/schemas/latest/opentp.schema.json
Eventshttps://opentp.dev/schemas/latest/event.schema.json
Dictionarieshttps://opentp.dev/schemas/latest/dict.schema.json
Field (shared)https://opentp.dev/schemas/latest/field.schema.json
Version (shared)https://opentp.dev/schemas/latest/version.schema.json

The schemas check the shape of each file. Rules that need several files or merged layers (closed vocabulary, policy, presence, dictionaries, overlap) are checked by validators; see Validator-only rules.

Version

Section titled “Version”

All OpenTrackPlan files start with:

opentp: 2026-09

This declares the format version. A validator accepts exactly the version it implements; the reference CLI upgrades older plans with opentp migrate.

Extensions

Section titled “Extensions”

The core specification is designed to be portable across tools.

  • Any key that starts with x- (for example x-acme-team) is allowed on the fixed-shape objects of every file (the root, info, spec, targets, fields, items, event and dictionary objects, and more; see Extensions). Tools ignore the x-* keys they do not know.
  • x-opentp is reserved: it was the tooling extension container until 2026-01 and is invalid in 2026-09.
  • Field checks are a core keyword, checks, with portable named checks in spec.checks and tool-defined check ids (see Checks).
  • Tool settings such as key generation live in tool files, not in opentp.yaml (the reference CLI uses opentp.cli.yaml).

Semantics

Section titled “Semantics”

Some behavior is defined by normative semantics in addition to JSON schemas: