Specification Conventions

1. Requirement keywords

This specification, and every AI Discovery File specification published under /specifications/, uses the requirement keywords defined in BCP 14 — comprising RFC 2119 and RFC 8174.

The keywords are:

• MUST, REQUIRED, SHALL — an absolute requirement.
• MUST NOT, SHALL NOT — an absolute prohibition.
• SHOULD, RECOMMENDED — a strong recommendation. There may be valid reasons in particular circumstances to ignore the recommendation, but the implications must be understood.
• SHOULD NOT, NOT RECOMMENDED — a strong recommendation against, with the same caveat.
• MAY, OPTIONAL — truly optional. Implementers may choose freely.

1.1 Only uppercase forms are normative

Per RFC 8174:

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC 2119] [RFC 8174] when, and only when, they appear in all capitals, as shown here.

Lower-case forms of these words ("may", "should", "must" in regular prose) are not normative. They are ordinary English usage and carry no requirement weight.

This distinction allows specification text to read naturally — for example, "this section should help implementers..." is informative, while "implementations SHOULD validate the encoding..." is normative.

1.2 Boilerplate inclusion

Specification pages reference these conventions by linking to this page rather than copying the boilerplate text. A spec page that uses requirement keywords need only state, in its conventions or references section: "This specification uses the requirement keywords defined in Specification Conventions."

2. Document status

Every specification page carries a status indicator near its header. Four values are used:

Draft

Under active development; the specification may change in incompatible ways before reaching Stable. Implementers should expect breakage.

Stable

Published and recommended for implementation. Backwards-compatible additions may occur in MINOR versions; breaking changes only in MAJOR versions, with deprecation notice.

Deprecated

Still valid but discouraged for new implementations. A successor specification or replacement is expected. Validators may emit warnings for files that conform to a deprecated specification.

Retired

No longer maintained or recommended. Existing implementations may continue to use the specification, but no further changes will be published. Validators may treat conformance to a retired specification as a failure.

The W3C-style "Candidate" intermediate state is intentionally not used. The set above keeps the status meaningful without unnecessary procedural overhead.

2.1 Status block format

Each spec page renders a status block near the top, containing the status value, a one-sentence meaning, and a link to this page. The visual style of the block depends on the status (calm tones for Stable; warmer tones for Draft; muted tones for Deprecated and Retired) so that readers can spot non-stable specs at a glance.

3. Versioning

Each specification follows Semantic Versioning 2.0.0:

• MAJOR — backwards-incompatible changes (e.g. removing a required field, changing a file's format fundamentally).
• MINOR — backwards-compatible additions (e.g. new optional field, new section, expanded validation guidance).
• PATCH — backwards-compatible corrections (e.g. fixing typos, broken links, ambiguous wording).

Versions are tracked in three places per specification, all kept in sync at every release: the rendered specification page, the JSON data file (*-specification.json), and the YAML data file (*-specification.yaml). A consistency audit verifies that all three carry identical version numbers.

The complete versioning and deprecation policy is documented at /specifications/versioning/: MAJOR / MINOR / PATCH commitments, the deprecation timeline, and the lifecycle from Stable through Deprecated to Retired.

3.1 Schema URL versioning

JSON Schemas published under /specifications/<file>/ are mirrored at versioned paths so publisher references can pin to a specific schema version that will never change. The convention:

• Versioned URL: /specifications/<file>/v1/<file>.schema.json. Once published at v1, this URL is permanent. It will not change shape across MINOR releases. If a future breaking change is needed, a new v2 URL is published alongside it; v1 continues to serve the v1 schema for as long as the specification line is supported.
• Unversioned ("latest") URL: /specifications/<file>/<file>.schema.json. Always serves the current major version's schema. Convenient for publishers who want to track the latest without pinning, but its shape can change when a new major version is published.

Publishers SHOULD reference the versioned URL via $schema in their own files when they need stability across future spec revisions. Publishers MAY use the unversioned URL when they want to follow the latest schema automatically.

Validators MUST accept either URL form. The Specification Registry lists both: schemaUrl (the canonical versioned URL) and schemaUrlLatest (the unversioned alias).

4. Cross-references and anchors

Section anchors use lower-case hyphenated slugs based on section content (e.g. #requirement-keywords, not #section-1). This makes URLs stable across re-numbering and self-describing when shared.

Numbered requirement clauses inside a specification are tagged with stable IDs of the form ADF-<FILE>-<NNN> — for example, ADF-IDENT-001 for "identity.json MUST contain a name field." Test vectors and validator output reference these IDs directly.

Cross-references between specifications use absolute anchors:

see requirement keywords

This avoids ambiguity when a spec is read in isolation.

5. Language and style

Specifications are written in British English (organisation, behaviour, optimisation). Where international consistency matters (e.g. file format names, technical terms drawn from RFCs), American English may appear in quoted material; this is preserved as written.

Specification prose is calm and precise. Marketing language, hyperbole, and unsupported claims are out of place. Examples are concrete and verifiable.

5.1 Language declaration in publisher files

Every AI Discovery File MAY declare the natural language of its human-readable content using a BCP 47 language tag (e.g. en-GB, fr-FR, de, pt-BR). The field is optional. When absent, consumers SHOULD NOT assume a default; they MAY infer from Content-Language HTTP headers or page-level <html lang> attributes as a fallback.

The shape of the declaration depends on the file format:

• Text-based files (llms.txt, ai.txt, brand.txt, faq-ai.txt, developer-ai.txt): a Lang: header at the top of the file. Example: Lang: en-GB.
• JSON-based files (ai.json, identity.json): a top-level language property. Example: "language": "en-GB".
• HTML-based files (llms.html): the standard <html lang="en-GB"> attribute. No additional declaration is needed.
• Format-defined files (llm.txt is a redirect, robots-ai.txt carries no human-language prose): the language declaration does not apply.

Validators MUST treat any declared value as informational and MUST NOT fail conformance solely on language-tag content. They MAY warn when the tag is malformed (not a valid BCP 47 tag).

Multi-language sites SHOULD publish separate files per locale at conventional sub-paths (e.g. /fr/llms.txt, /de/llms.txt) and link between them from the canonical file at /llms.txt. A full multi-language addressing convention is forthcoming as part of Phase 6 of the spec standardisation work.

6. Changes to these conventions

Material changes to this page propagate to every specification because each spec links here rather than restating the rules. Changes are announced in the changelog with a clear effective date. Existing specifications carry forward their status under the version of these conventions in effect at the time of their last release.

References

• BCP 14 — Best current practice combining RFC 2119 and RFC 8174.
• RFC 2119 — Key words for use in RFCs to indicate requirement levels.
• RFC 8174 — Ambiguity of uppercase vs lowercase in RFC 2119 key words.
• Semantic Versioning 2.0.0
• Conformance — The three conformance classes (Essential, Recommended, Complete), publisher and validator conformance criteria, and Directory verification.
• Specification Registry: machine-readable single source of truth for every AI Discovery File (media types, paths, paired files, precedence rules, schema URLs).
• Versioning and Deprecation Policy: Semantic Versioning 2.0.0 commitments, deprecation timeline, and the specification lifecycle.
• Governance and Editorial Process: how proposals move through review, the working principles, and the contribution path.
• Security and Privacy Considerations: trust model, content-injection patterns to avoid, GDPR considerations, integrity primitives.
• HTTP Behaviour: status codes, redirect handling, soft-404 detection, caching, rate limits.
• Processing Model: the seven-stage algorithm conformant consumers apply (discover, fetch, validate, resolve identity, resolve permissions, detect contradictions, emit).
• AI Consumer Guidance: what AI systems should do with AI Discovery Files.
• Test Vectors: canonical test suite for validators.
• Licensing & Trademark — How specification text, schemas, and the project name may be used.