{
  "$id": "https://open.divekit.app/schemas/references/references.schema.v1.1.0.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Dive Kit References Schema",
  "description": "Vetted references behind Dive Kit's calculators and guide: the papers, books, standards and articles the numbers are built from, the planners they are cross-checked against, and the community sources that shaped the tools. Each record says what it is authoritative for so an assistant can cite it instead of searching the web.",
  "type": "object",
  "properties": {
    "$schema": { "type": "string", "description": "Reference to this schema URL." },
    "meta": {
      "type": "object",
      "description": "Metadata about this dataset version.",
      "properties": {
        "version": { "type": "string", "description": "Date-based tag for this dataset (e.g. '2026.09.26.1')." },
        "generated_at": { "type": "string", "format": "date-time", "description": "ISO timestamp when the dataset was last generated." }
      },
      "required": ["version", "generated_at"]
    },
    "references": {
      "type": "array",
      "description": "All references in this dataset.",
      "items": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "pattern": "^ref-[a-z0-9\\-]+$", "description": "Unique id, kebab-case, prefixed 'ref-'. Example: 'ref-baker-understanding-m-values'." },
          "title": { "type": "string", "description": "Title of the work as published." },
          "authors": { "type": "array", "items": { "type": "string" }, "description": "Authors or issuing body, in published order. Empty for anonymous web pages." },
          "year": { "type": ["integer", "null"], "description": "Year of publication, or null when undated (living web pages)." },
          "type": {
            "type": "string",
            "enum": ["paper", "book", "standard", "manual", "article", "blog", "thread", "dataset", "website", "talk", "software", "video", "podcast", "course_material", "report"],
            "description": "What kind of source this is."
          },
          "publisher": { "type": "string", "description": "Publisher, journal, agency or site." },
          "url": { "type": "string", "format": "uri", "description": "Canonical URL. Prefer the publisher or an open archive over a mirror." },
          "doi": { "type": "string", "description": "DOI without the resolver prefix, e.g. '10.1002/cphy.c091004'." },
          "access": {
            "type": "string",
            "enum": ["open", "paywalled", "borrow", "print"],
            "description": "open: free online; paywalled: behind a subscription; borrow: lendable scan (e.g. archive.org); print: no reliable online copy."
          },
          "format": {
            "type": "string",
            "enum": ["html", "pdf", "video", "audio", "print"],
            "description": "Optional. What opening the url gives you: a web page, a PDF, a video, audio, or print only."
          },
          "recommended_by": {
            "type": "array",
            "items": { "type": "string" },
            "description": "Optional. Communities or publications that point divers to this source, e.g. 'r/scuba wiki', 'ScubaBoard sticky', 'DAN Alert Diver'."
          },
          "topics": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "string",
              "enum": [
                "deco_theory", "gradient_factors", "oxygen_toxicity", "gas_density", "icd", "hpns", "ccr",
                "gas_selection", "gas_planning", "gas_blending", "oxygen_handling", "real_gas", "cylinders",
                "buoyancy", "breathing_rate", "conventions", "training", "emergencies", "cross_checks", "community"
              ]
            },
            "description": "Guide topics this reference supports. Aligned with the Dive Kit MCP guide topic names."
          },
          "authoritative_for": { "type": "string", "maxLength": 200, "description": "One plain sentence: what Dive Kit relies on this source for." },
          "notes": { "type": "string", "description": "Optional caveats: superseded editions, bot-blocking hosts, which section to read." },
          "checked_at": { "type": "string", "format": "date", "description": "Date the URL was last verified to resolve." }
        },
        "required": ["id", "title", "authors", "type", "access", "topics", "authoritative_for", "checked_at"],
        "additionalProperties": false
      }
    }
  },
  "required": ["meta", "references"],
  "additionalProperties": false
}