{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://code.s-nc.org/Kevoun/ARD/kernel/schema/attestation.schema.json",
  "title": "ARD attestation frontmatter (normative minimum)",
  "description": "The normative-minimum YAML frontmatter every per-source attestation carries (ARD SPEC §4.2). This is an architecture-tier data contract — its required minimum changes only on a MAJOR bump. Per-source-class and cross-class fields (ARD CATALOGS §2) are optional extensions, so additionalProperties is permitted; documenting an optional extension as a named property is additive (MINOR).",
  "x-ard-tier": "architecture",
  "type": "object",
  "required": ["source_handle", "fetched", "provenance"],
  "properties": {
    "source_handle": {
      "type": "string",
      "pattern": "^[\\w-]+$",
      "description": "Stable source handle. MUST equal the [handle] in citing prose; resolves to this attestation file. Canonical form is ASCII-lowercase ([a-z0-9-]+) — the lint flags uppercase or non-ASCII (homoglyph) handles as non-canonical; the pattern here stays permissive ([\\w-]+) so a malformed handle surfaces rather than failing schema validation silently, and a future MAJOR may tighten it."
    },
    "fetched": {
      "type": "string",
      "format": "date",
      "description": "Date the source was fetched, YYYY-MM-DD."
    },
    "source_url": {
      "type": "string",
      "description": "Source URL. One of source_url / source_path is required."
    },
    "source_path": {
      "type": "string",
      "description": "Local path for ingested sources. One of source_url / source_path is required."
    },
    "provenance": {
      "type": "string",
      "description": "Artifact-local warrant. For a source-direct attestation, typically 'source-direct'. (Provenance values are inventory — ARD CATALOGS §8 — so not enum-constrained here.)"
    },
    "extraction_pipeline": {
      "type": "string",
      "description": "Optional cross-class extension (ARD CATALOGS §2). Names the pipeline used to extract the source (e.g. a PDF/EPUB extractor) for drift-detectability across re-extractions. Not enum-constrained — inventory. Optional: not in the normative minimum."
    },
    "substrate_confidence": {
      "type": "string",
      "description": "Optional cross-class extension (ARD CATALOGS §2). Engagement depth: 'source-direct' / 'search-summary' / 'snippet-thin' / 'unspecified'. Omission currently defaults to source-direct, but THAT DEFAULT IS DEPRECATED (v0.6.0): during a grace period omission still reads source-direct and the lint emits a deprecation warning; a future MAJOR flips the default to fail-closed — omission will read 'unspecified', which lints as a substrate gap (reduced-substrate-attestation). Declare the value explicitly. Distinct from provenance (which names how the artifact was authored). Optional: not in the normative minimum."
    }
  },
  "anyOf": [
    { "required": ["source_url"] },
    { "required": ["source_path"] }
  ],
  "additionalProperties": true
}