# ai.json Specification
# Version: 1.8.0
# https://www.ai-visibility.org.uk/specifications/ai-json/

meta:
  title: ai.json Specification
  description: The canonical specification for ai.json files - machine-parseable AI interaction guidance in JSON format.
  version: "1.8.0"
  versionDate: "2026-06-11"
  canonicalUrl: https://www.ai-visibility.org.uk/specifications/ai-json/
  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-06-11T00:00:00Z"
  language: en-GB

specification:
  filename: ai.json
  location: Website root directory
  urlPattern: https://example.com/ai.json
  mimeType: application/json
  encoding: UTF-8
  purpose: Provide machine-parseable AI interaction guidance in strict JSON format. Enables AI systems to programmatically determine permissions, restrictions, and behavioural expectations.

  schema:
    url: https://www.ai-visibility.org.uk/specifications/ai-json/v1/ai-json.schema.json
    latestUrl: https://www.ai-visibility.org.uk/specifications/ai-json/ai-json.schema.json
    version: "1.0.0"

  format:
    type: JSON
    description: Strict JSON, schema-validated
    requirements:
      valid: MUST be valid JSON per RFC 8259
      schema: MUST include $schema reference
      encoding: Must be UTF-8 encoded

  properties:
    required:
      - property: $schema
        type: string
        description: Reference to the ai.json JSON Schema. Publishers SHOULD pin to the versioned URL for stability; the unversioned URL is also accepted as a 'latest' alias.
        example: https://www.ai-visibility.org.uk/specifications/ai-json/v1/ai-json.schema.json

      - property: name
        type: string
        description: Official organisation name

      - property: url
        type: string
        format: uri
        description: Canonical website URL

      - property: permissions
        type: array
        description: List of permitted AI actions
        items: Permission objects with action and optional conditions

      - property: restrictions
        type: array
        description: List of prohibited AI actions
        items: Restriction objects with action and reason

    recommended:
      - property: attribution
        type: object
        description: Attribution requirements
        properties:
          - property: required
            type: boolean
          - property: format
            type: string
          - property: examples
            type: array

      - property: contact
        type: object
        description: Contact information for AI-related queries
        properties:
          - property: email
            type: string
            format: email

      - property: scope
        type: object
        description: Scope of these permissions
        properties:
          - property: appliesTo
            type: string
          - property: excludes
            type: array

    optional:
      - property: language
        type: string
        description: BCP 47 language tag (e.g. en-GB) declaring the natural language of human-readable content in this file. See /specifications/conventions/#language-declaration.
        example: en-GB

      - property: licensing
        type: object
        description: Content licensing information
        properties:
          - property: contentLicense
            type: string
          - property: aiTrainingAllowed
            type: boolean

      - property: metadata
        type: object
        description: File metadata
        properties:
          - property: version
            type: string
          - property: lastUpdated
            type: string
            format: date
          - property: generator
            type: string

  permissionObject:
    description: Structure for permission entries
    properties:
      action:
        type: string
        description: The permitted action identifier
        required: true
      description:
        type: string
        description: Human-readable description
      conditions:
        type: array
        description: Conditions that apply to this permission

  restrictionObject:
    description: Structure for restriction entries
    properties:
      action:
        type: string
        description: The prohibited action identifier
        required: true
      reason:
        type: string
        description: Why this action is prohibited
      severity:
        type: string
        enum:
          - must-not
          - should-not
        description: Severity level of the restriction

  validation:
    rules:
      - MUST be valid JSON
      - MUST validate against ai.json JSON Schema
      - MUST include $schema reference
      - MUST include name, url, permissions, and restrictions
      - URLs MUST be valid URI format
      - Email addresses MUST be valid email format
      - Extension properties beyond this specification are permitted and MAY be ignored by consumers, but MUST NOT redefine or contradict documented properties
    commonErrors:
      - Missing $schema reference
      - Invalid JSON syntax
      - Missing required properties
      - Type mismatches (string vs array)
      - Invalid URL or email formats
      - Contradictory permissions and restrictions

  relationships:
    ai.txt: Human-readable equivalent - should contain consistent information
    llms.txt: Identity information must match
    identity.json: Organisation details must be consistent

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

versionHistory:
  - version: "1.8.0"
    date: "2026-06-11"
    changes: "Schema validation opened to extension properties (additionalProperties is now true). The $schema property accepts both the unversioned schema URL and the versioned /v1/ URL. The canonical example now validates against the published schema."
  - 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 expanded optional properties (scope, training, dataRetention) and Content Not Permitted guidance. Clarifies JSON-specific requirements and validation rules.
  - version: "1.0.0"
    date: "2026-01-12"
    changes: Initial specification release. Establishes JSON format for AI interaction guidance with JSON Schema validation.
