Skip to main content

Headers

The header is the first meaningful line of any SDIF document. It tells the parser what version of the format to expect and what kind of document this is. No content may appear before the header except blank lines and comments.

The Version Directive​

Every SDIF document begins with a version directive:

@sdif 1.0

The @sdif token is the format identifier. 1.0 is the version number. Together they define the parsing contract: tools that implement SDIF 1.0 can read this document.

Source documents and canonical documents both use @sdif 1.0. The version directive alone does not distinguish between them — that is the role of the profile directive.

AI Projection Documents​

Documents generated by or annotated with AI content use a different header token:

@sdif.ai 1.0

The .ai suffix signals that this document is an AI projection rather than authoritative structured data. Parsers and tools treat @sdif.ai documents with appropriate caution: they may contain AI-inferred values, incomplete information, or errors that require human review before the content is promoted to a source document.

An AI projection may be produced by sdif ai or sdif from-ai. When a projection is reviewed and accepted, it is typically converted back to @sdif 1.0 by a human before being stored as authoritative data.

The Profile Directive​

The profile directive is optional and appears on the line immediately after the version directive:

@sdif 1.0
@profile source

It names the specific syntax profile the document targets. Two profiles exist in SDIF 1.0:

@profile source​

@sdif 1.0
@profile source

Marks the document as a human-authored source file. Source documents are the permissive form of SDIF: they may contain comments, blank lines, varied indentation, and fields in any order. Parsers in source mode accept this flexibility.

The @profile source directive is optional. A document with @sdif 1.0 and no profile directive is treated as source by default. Adding @profile source makes the intent explicit, which some teams prefer for clarity.

@profile canonical-syntax-v1​

@sdif 1.0
@profile canonical-syntax-v1

Marks the document as having been produced by the SDIF canonicalizer under the canonical-syntax-v1 contract. Canonical documents:

  • Contain no comments
  • Contain no blank lines between blocks
  • Use exactly two-space indentation for table rows and relation triples
  • Use exactly one literal tab character between column values
  • Have fields, rows, and relations in a deterministic, sorted order

A parser encountering @profile canonical-syntax-v1 may apply stricter validation — for example, rejecting comments or out-of-order fields — because the canonical profile guarantees those properties. In practice, most tools simply read canonical documents the same way they read source documents, since canonical form is a strict subset of valid SDIF.

The canonical-syntax-v1 profile label is versioned. Future canonicalization contracts may introduce canonical-syntax-v2 with updated ordering or formatting rules. Versioning the profile ensures that tooling can distinguish which contract produced a given canonical document.

What Parsers Do with the Header​

When a parser reads the header, it:

  1. Verifies that the @sdif (or @sdif.ai) token is present. If it is missing or misspelled, the file is not an SDIF document.
  2. Records the version number. If the version is not supported, the parser reports an error.
  3. Checks for a @profile directive on the next line. If present, it applies the corresponding parsing mode. If absent, it defaults to source mode.

Parsers do not require a profile directive. Omitting it is common in hand-authored documents.

Examples​

A minimal source document with no profile declaration:

@sdif 1.0
kind Note
id my.note
body "A quick note."

A source document with an explicit profile:

@sdif 1.0
@profile source
# Written by hand during planning session
kind Plan
id q3.plan
status draft

A canonical document produced by sdif canon:

@sdif 1.0
@profile canonical-syntax-v1
kind Plan
id q3.plan
schema example.plan.v1
status draft
title "Q3 plan"

An AI projection document:

@sdif.ai 1.0
kind Plan
id q3.plan.ai-draft
title "Q3 plan (AI draft)"
status draft

The AI projection uses @sdif.ai 1.0 and carries no profile directive. Tools that process AI projections know to treat the content as provisional.