Skip to content

Specification

Reference

The authoritative spec

The full, normative definition of 3md is SPEC.md in the repository:

github.com/CorvidLabs/3md/blob/main/SPEC.md

This page is a pointer with a short summary. When the prose here and the spec disagree, the spec wins; and when the spec and the shared conformance vectors disagree, the vectors win (see below).

The format is at version 1.0: stable, with a frozen grammar.

Conformance rules in brief

A conforming parser:

  • Requires a frontmatter block fenced by lines containing exactly ---. The frontmatter is a flat, line-based key: value mini-format (not YAML).
  • Requires the 3md key (the magic marker) but never validates its value, so it is version-lenient: older markers like 0.1 stay valid.
  • Treats axis (default layer) and title as reserved, case-insensitive keys, and preserves every other key as string metadata.
  • Starts a plane at each @plane directive at column 0 and outside any code fence, requiring a finite-decimal z that is unique across planes.
  • Treats a frontmatter-only document with no directives as one implicit plane at z = 0.
  • Leaves [[z=N|text]] cross-plane links in the body verbatim and exposes them through a separate extraction step that reports whether each target exists.
  • Round-trips: serializing a parsed document and parsing the result yields an equivalent document.
  • Rejects the defined error cases: missingFrontmatter, invalidFrontmatter, missingVersion, missingPlanePosition, invalidPlaneDirective, and duplicatePlane.

The conformance suite is the contract

The portable test vectors, not the prose, are the authoritative definition of conforming behavior. Any implementation that passes them is conforming, and any change that would alter their expected results is a breaking change. This is what keeps the three parsers (Swift, TypeScript, Rust) behaving identically.

Stability guarantees

  • The 1.0 grammar is frozen and will not change within the 1.x line.
  • Additive features ship in future MINOR versions (1.1, 1.2, ...) and must never invalidate a document that conformed to an earlier 1.x version.
  • Only a new MAJOR version (2.0) may break compatibility. Because parsers are version-lenient, bumping the 3md: value alone does not change how a document parses.

See also