# llms.html Specification
# Version: 1.7.0
# https://www.ai-visibility.org.uk/specifications/llms-html/

meta:
  title: llms.html Specification
  description: The canonical specification for llms.html files - human-readable HTML presentation of AI identity information.
  version: "1.7.0"
  versionDate: "2026-05-11"
  canonicalUrl: https://www.ai-visibility.org.uk/specifications/llms-html/
  publisher:
    name: 365i
    url: https://www.365i.co.uk/
  license:
    name: Creative Commons Attribution 4.0 International
    identifier: CC-BY-4.0
    url: https://creativecommons.org/licenses/by/4.0/
  datePublished: "2026-01-12T00:00:00Z"
  dateModified: "2026-05-11T00:00:00Z"
  language: en-GB

specification:
  filename: llms.html
  location: Website root directory
  urlPattern: https://example.com/llms.html
  mimeType: text/html
  encoding: UTF-8
  purpose: Provide a human-readable HTML presentation of the information contained in llms.txt, with enhanced formatting and structured data.

  relationship:
    sourceFile: llms.txt
    note: llms.html presents equivalent information to llms.txt in human-readable HTML format. The content authority is llms.txt.

  format:
    type: HTML5
    description: Valid HTML5 document with semantic markup and Schema.org structured data
    requirements:
      doctype: "<!DOCTYPE html>"
      language: lang attribute on html element
      charset: UTF-8 via meta charset
      viewport: Responsive viewport meta tag

  structure:
    required:
      - element: head
        contents:
          - title element matching organisation name
          - meta description
          - charset declaration
          - canonical link to llms.txt
          - Schema.org JSON-LD structured data
      - element: body
        contents:
          - h1 heading with organisation name
          - Summary paragraph or section
          - Sectioned content matching llms.txt sections

    recommended:
      - element: nav
        purpose: Table of contents linking to sections
      - element: footer
        purpose: Last updated date and link to llms.txt

  structuredData:
    required:
      - type: Organization
        description: Schema.org Organization representing the entity
    recommended:
      - type: WebPage
        description: Schema.org WebPage for the document itself
      - type: BreadcrumbList
        description: Navigation context
    format: JSON-LD in script tag within head element

  accessibility:
    requirements:
      - Valid heading hierarchy (h1 > h2 > h3)
      - Sufficient colour contrast (WCAG AA minimum)
      - Keyboard navigable
      - Screen reader compatible
      - Descriptive link text
      - Alt text for any images

  validation:
    rules:
      - MUST be valid HTML5
      - MUST pass W3C HTML validation
      - MUST contain equivalent content to llms.txt
      - MUST include Schema.org structured data
      - SHOULD pass WCAG 2.1 AA accessibility checks
    commonErrors:
      - Missing or invalid structured data
      - Content divergence from llms.txt
      - Invalid HTML structure
      - Accessibility failures
      - Missing canonical link to llms.txt

  relationships:
    llms.txt: Source content - llms.html must present equivalent information
    llm.txt: Alternative source with identical content
    identity.json: Should have consistent identity information

example:
  url: https://www.ai-visibility.org.uk/specifications/examples/llms.html
  business: Horizon Strategic Consulting

versionHistory:
  - version: "1.7.0"
    date: "2026-05-11"
    changes: "Phase 6 standardisation release. Added /specifications/roadmap/ (theme-pegged forward plan with Active/Next/Future/On hold status flags), /specifications/extensions/ (rules for experimental x- prefixed files and the promotion path), and /specifications/i18n-a11y/ (multi-language publication, locale-tagged identity fields, RTL handling, accessibility of llms.html). Added the Discovery: directive to the robots-ai.txt specification (publishers MAY advertise AI Discovery Files on the same host). Added a formal media-type stance to the HTTP behaviour page (existing IANA types, no bespoke registrations). Expanded the file integrity and signing section on the security and privacy page with four candidate mechanisms, cross-cutting concerns, and interim publisher / consumer guidance. The Discovery: directive is the only normative addition to publisher behaviour; all other additions are forward-looking documentation."
  - version: "1.6.0"
    date: "2026-05-11"
    changes: "Phase 5 standardisation release. Added /specifications/related-standards/ (positioning vs llmstxt.org, IETF AI Preferences, robots.txt, Schema.org, BCP 14, JSON Schema 2020-12, SemVer) and /specifications/implementations/ (public record of conformant implementations, IETF-style). Added an explicit llmstxt.org backward-compatibility statement to the llms.txt specification. Added a formal multi-domain and subdomain scoping rule to both the llms.txt and identity.json specifications (host-scoped files, cross-host identity asserted via sameAs). No normative requirements changed for existing publishers; the new scoping rules formalise behaviour the specification already implied."
  - version: "1.5.0"
    date: "2026-05-11"
    changes: "Phase 4 standardisation release. Added /specifications/processing-model/ (seven-stage algorithm for conformant consumers), /specifications/consumer-guidance/ (what AI systems should do with AI Discovery Files), /specifications/test-vectors/ (canonical test suite framing), and reference-implementation framing on the AI Visibility Checker. No normative requirements changed."
  - version: "1.4.0"
    date: "2026-05-11"
    changes: "Phase 3 standardisation release. Added /specifications/versioning/ (Semantic Versioning 2.0.0 commitments, deprecation timeline, lifecycle), /specifications/governance/ (proposal lifecycle, editorial process, working principles), /specifications/security-privacy/ (trust model, content-injection patterns, GDPR considerations, integrity primitives roadmap), and /specifications/http-behaviour/ (status codes, redirects, soft-404 detection, caching, rate limits). No normative requirements changed."
  - version: "1.3.0"
    date: "2026-05-11"
    changes: "Phase 2 standardisation release. Added formal conformance specification (Essential / Recommended / Complete classes). Published machine-readable registry at /specifications/registry.json, spec meta-schema, and validator-output schema. Introduced versioned JSON Schema URLs (/v1/) alongside unversioned 'latest' aliases. Added optional BCP 47 language declaration field across all applicable AI Discovery Files. No normative requirements changed."
  - version: "1.2.0"
    date: "2026-05-10"
    changes: "Phase 1 standardisation release. Added 'Status of This Document' block (Stable). Normalised normative requirement keywords to uppercase per RFC 2119 and RFC 8174. Added References section linking to /specifications/conventions/ and /licensing/. No normative requirements changed."
  - version: "1.1.1"
    date: "2026-02-13"
    changes: Added AI Visibility Directory registration guidance. Minor documentation update.
  - version: "1.1.0"
    date: "2026-01-14"
    changes: 'Added "Optional Content" section with specific examples. Added "Content Not Permitted" section clarifying what must not be included in llms.html files.'
  - version: "1.0.0"
    date: "2026-01-12"
    changes: Initial publication. Defines requirements for human-readable HTML presentation of llms.txt content with Schema.org structured data.
