brief.md spec version pinning — `spec_version` and forward compatibility
brief.md frontmatter declares `spec_version` so consumers know which spec version to interpret the file against. The spec is forward-compatible within a major version; consumers should reject files with newer minor versions only if they have to.
Implementers building tools that consume brief.md need to know how to handle version mismatches between the file's declared version and the parser's capabilities.
Version semantics
The spec follows semantic versioning. Major version bumps (0.x → 1.0) introduce breaking changes — consumers MUST reject files with major versions newer than they support. Minor version bumps (0.1.0 → 0.2.0) add fields but preserve existing semantics — consumers SHOULD accept newer-minor files and ignore unknown fields. Patch bumps (0.1.0 → 0.1.1) are clarifications — consumers MUST accept patch differences.
Frontmatter declaration
Every brief.md declares `spec_version: 0.1.0` in frontmatter alongside `spec_url: https://theintegrityframework.org/specs/brief-md/v0.1.0`. The URL pins the parser to a canonical spec definition; consumers can fetch the spec from that URL to verify their interpretation matches the operator's intent.
Forward compatibility rules
A consumer at spec_version 0.1.0 reading a file at 0.2.0: parse what you understand, ignore unknown fields, surface a soft warning to the operator. A consumer at 0.2.0 reading a file at 0.1.0: parse normally — older files are valid forever within a major version. A consumer reading a file with a newer major version: reject with a clear error pointing the operator at the spec URL.
Brand version vs spec version
Two version fields exist: `spec_version` (which spec the file conforms to) and `brand_version` (which iteration of this brand's brief). Spec version drifts slowly (months between minor versions); brand version drifts whenever the operator updates positioning, voice, or assets. PRAPI's current brief is `brand_version: 1.3.0` against `spec_version: 0.1.0`.
PRAPI's brief.md frontmatter declares `spec_version: 0.1.0` and `brand_version: 1.3.0`. The brand has iterated three times since launch (positioning shifts during Phase 0-1.5); the spec version has stayed at 0.1.0 since publication.
FAQ
What happens if I declare a spec_version my parser does not support?
A well-behaved parser surfaces the version mismatch and either (a) parses what it understands and warns, or (b) rejects with a clear error pointing at the spec URL. The PRAPI canonical parser does (a) for newer-minor files and (b) for newer-major files.
How often does the spec version bump?
The spec is at 0.1.0 as of 2026-05. Minor version bumps are quarterly to bi-annual, anchored on real implementation pressure. The 1.0 release will signal stability.
Should I always declare the latest spec_version?
Declare the version you authored against. If your brief was written against 0.1.0 and a 0.2.0 release adds optional fields you have not adopted, your file should still declare 0.1.0 — that's the version it actually conforms to.
What is the difference between spec_version and brand_version?
spec_version is the version of the brief.md format (the schema). brand_version is the version of your brand's content (the data). spec_version changes when the format evolves; brand_version changes when your positioning, assets, or voice evolves.
Run brief.md in PRAPI.
PRAPI is the canonical brief.md implementation. Every brand in your portfolio gets its own brief.md, voice-validated drafts on every pitch, and Git-canonical authoring.
Sign in →