{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://www.ai-visibility.org.uk/specifications/spec-meta.schema.json",
  "title": "AI Discovery Files Specification Meta-Schema",
  "description": "Describes the shape of each *-specification.json data file. Each ADF specification has a JSON twin (and a YAML twin) that carries the same content as the rendered specification page. This meta-schema enforces the structure of the meta block and the versionHistory array; the specification block varies per spec and is left open.",
  "type": "object",
  "required": ["meta", "specification", "versionHistory"],
  "properties": {
    "meta": {
      "type": "object",
      "description": "Specification metadata — version, publisher, licence, dates.",
      "required": [
        "title",
        "description",
        "version",
        "versionDate",
        "canonicalUrl",
        "publisher",
        "license",
        "datePublished",
        "dateModified",
        "language"
      ],
      "properties": {
        "title": {
          "type": "string",
          "minLength": 1,
          "description": "Human-readable title of the specification (e.g. 'llms.txt Specification')."
        },
        "description": {
          "type": "string",
          "minLength": 1,
          "description": "One-line description of what the specification covers."
        },
        "version": {
          "type": "string",
          "pattern": "^\\d+\\.\\d+\\.\\d+$",
          "description": "Semantic version (Semver 2.0.0) of this specification. MUST match the corresponding entry in versions.php and the YAML twin."
        },
        "versionDate": {
          "type": "string",
          "format": "date",
          "description": "ISO 8601 date (YYYY-MM-DD) on which this version was published."
        },
        "canonicalUrl": {
          "type": "string",
          "format": "uri",
          "description": "Canonical URL of the rendered specification page."
        },
        "publisher": {
          "type": "object",
          "required": ["name", "url"],
          "properties": {
            "name": { "type": "string", "minLength": 1 },
            "url": { "type": "string", "format": "uri" }
          },
          "additionalProperties": true
        },
        "license": {
          "type": "object",
          "required": ["name", "identifier", "url"],
          "properties": {
            "name": { "type": "string", "minLength": 1 },
            "identifier": {
              "type": "string",
              "description": "SPDX identifier (e.g. CC-BY-4.0)."
            },
            "url": { "type": "string", "format": "uri" }
          },
          "additionalProperties": false
        },
        "datePublished": {
          "type": "string",
          "format": "date-time",
          "description": "ISO 8601 timestamp of first publication."
        },
        "dateModified": {
          "type": "string",
          "format": "date-time",
          "description": "ISO 8601 timestamp of last modification. MUST equal versionDate at the day-precision level for the current release."
        },
        "language": {
          "type": "string",
          "description": "BCP 47 language tag (e.g. en-GB)."
        },
        "basedOn": {
          "type": "object",
          "description": "Optional reference to a prior or related convention this specification builds on.",
          "properties": {
            "name": { "type": "string" },
            "url": { "type": "string", "format": "uri" }
          },
          "additionalProperties": true
        },
        "alignment": {
          "type": "object",
          "description": "Optional reference to an external vocabulary or standard this specification aligns with.",
          "properties": {
            "vocabulary": { "type": "string" },
            "url": { "type": "string", "format": "uri" }
          },
          "additionalProperties": true
        }
      },
      "additionalProperties": true
    },
    "specification": {
      "type": "object",
      "description": "Specification body. Shape varies per ADF; common keys include filename, location, urlPattern, mimeType, encoding, purpose, format, sections, validation, requirements. Left open here so each spec can model its domain naturally.",
      "minProperties": 1
    },
    "example": {
      "type": "object",
      "description": "Canonical example for this specification. Shape varies per ADF (e.g. a content string for text-based files, a sample JSON object for JSON-based files). Left open so each spec can model its example naturally."
    },
    "versionHistory": {
      "type": "array",
      "description": "Ordered history of releases, most recent first. The first element MUST match meta.version and meta.versionDate.",
      "minItems": 1,
      "items": {
        "type": "object",
        "required": ["version", "date", "changes"],
        "properties": {
          "version": {
            "type": "string",
            "pattern": "^\\d+\\.\\d+\\.\\d+$"
          },
          "date": {
            "type": "string",
            "format": "date"
          },
          "changes": {
            "type": "string",
            "minLength": 1,
            "description": "Plain-English summary of what changed in this release."
          }
        },
        "additionalProperties": false
      }
    }
  },
  "additionalProperties": false
}