{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://publedge.org/schema/instrument.schema.json",
  "title": "PubLedge Instrument (polymorphic)",
  "description": "Polymorphic frontmatter schema for every interpretive-instrument record in the PubLedge registry. Discriminates on `type`. Supersedes schema/jia.schema.json and schema/rma.schema.json (retained for backward compatibility). See _workshop/CONTENT-GUIDE.md §'Interpretive-instrument core fields' for field semantics.",
  "type": "object",
  "required": ["id", "type", "status", "editorial_status", "source", "jurisdiction", "authority"],
  "properties": {
    "@type": { "type": "string", "format": "uri" },
    "id": {
      "type": "string",
      "description": "Canonical identifier: {jurisdiction}-{authority}-{kind}-{YYYY-NNN}.",
      "pattern": "^[a-z]{2}(-[a-z0-9]+)+-[a-z-]+-[a-z0-9-]+$"
    },
    "legacy_id": { "type": ["string", "null"] },
    "instance": { "type": ["string", "null"] },
    "slug": { "type": "string" },
    "title": { "type": "string", "minLength": 3 },
    "name": { "type": "string", "minLength": 3 },
    "type": {
      "type": "string",
      "enum": [
        "jia",
        "rma",
        "no-action-letter",
        "advisory-opinion",
        "private-letter-ruling",
        "revenue-ruling",
        "interpretive-letter",
        "statute"
      ]
    },
    "source": {
      "type": "string",
      "enum": [
        "authority-issued",
        "demonstration-remap",
        "publedge-original-draft",
        "authoritative-reference"
      ]
    },
    "status": {
      "type": "string",
      "enum": [
        "proposed",
        "enacted",
        "enforcing",
        "phased-enforcement",
        "pending-replacement",
        "expired",
        "superseded",
        "withdrawn",
        "terminated"
      ]
    },
    "editorial_status": {
      "type": "string",
      "description": "PubLedge editorial maturity. This field does not state whether the instrument is legally operative.",
      "enum": ["draft", "reviewed", "published"]
    },
    "jurisdiction": {
      "type": "string",
      "pattern": "^[a-z]{2,3}(-[a-z0-9]{2,})?$"
    },
    "authority": {
      "type": "string",
      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
    },
    "issued_by": { "type": ["object", "string", "null"] },
    "reliance_scope": {
      "type": ["string", "null"],
      "enum": [
        "requesting-party-only",
        "similarly-situated-third-parties",
        "public",
        "unspecified",
        null
      ]
    },
    "obligation_kind": {
      "description": "Requirement / restriction / permission classifier. May be a single value or a bracketed list.",
      "type": ["string", "array", "null"]
    },
    "requesting_party": { "type": ["string", "object", "null"] },
    "participating_party": { "type": ["string", "null"] },
    "interpreting_authority": { "type": ["string", "null"] },
    "issuing_authority": { "type": ["string", "null"] },
    "enforcement_authority": { "type": ["string", "null"] },
    "parties": { "type": ["array", "null"] },
    "program": { "type": ["string", "null"] },
    "enacted": { "type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" },
    "effective": { "type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" },
    "term_start": { "type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" },
    "term_end": { "type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" },
    "review_date": { "type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" },
    "last_verified": { "type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" },
    "created": { "type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" },
    "modified": { "type": ["string", "null"], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" },
    "commencement_date_trigger": { "type": ["string", "null"] },
    "supersedes": { "type": ["string", "null"] },
    "superseded_by": { "type": ["string", "null"] },
    "withdrawn_date": { "type": ["string", "null"] },
    "withdrawal_reason": { "type": ["string", "null"] },
    "withdrawn_by_instrument": { "type": ["string", "null"] },
    "authority_response": {
      "type": ["array", "null"],
      "description": "Optional authority-supplied responses or corrections. Entries annotate the record and never replace the original interpretation.",
      "items": {
        "type": "object",
        "required": ["from", "date", "position"],
        "properties": {
          "from": {
            "type": "string",
            "minLength": 1,
            "description": "Authority slug or authority name."
          },
          "date": {
            "type": "string",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
          },
          "position": {
            "type": "string",
            "enum": [
              "concurs",
              "disputes",
              "clarifies",
              "declines-to-comment",
              "superseded-by-official"
            ]
          },
          "statement": { "type": ["string", "null"] },
          "source": { "type": ["string", "null"], "format": "uri" },
          "signature": { "type": ["string", "null"] }
        },
        "additionalProperties": true,
        "anyOf": [
          { "required": ["statement"] },
          { "required": ["source"] }
        ]
      }
    },
    "redaction_level": {
      "type": ["string", "null"],
      "enum": ["none", "partial", "full", null]
    },
    "official_url": { "type": ["string", "null"], "format": "uri" },
    "official_ref": { "type": ["string", "null"] },
    "publication_citations": { "type": ["array", "null"] },
    "source_documents": { "type": ["array", "null"] },
    "extracted_text": { "type": ["string", "null"] },
    "statute_anchors": { "type": ["array", "null"] },
    "mitigations": { "type": ["array", "null"] },
    "provisions": { "type": ["array", "null"] },
    "timeline": { "type": ["array", "null"] },
    "disclaimer": { "type": ["string", "null"] }
  },
  "additionalProperties": true,
  "allOf": [
    {
      "if": { "properties": { "type": { "const": "rma" } }, "required": ["type"] },
      "then": {
        "allOf": [
          {
            "anyOf": [
              { "required": ["issuing_authority"] },
              { "required": ["enforcement_authority"] },
              { "required": ["parties"] }
            ]
          },
          {
            "anyOf": [
              {
                "properties": { "term_start": { "type": "string" } },
                "required": ["term_start"]
              },
              {
                "properties": { "commencement_date_trigger": { "type": "string", "minLength": 1 } },
                "required": ["commencement_date_trigger"]
              }
            ]
          }
        ]
      }
    },
    {
      "if": {
        "properties": { "type": { "enum": ["private-letter-ruling", "revenue-ruling"] } },
        "required": ["type"]
      },
      "then": { "required": ["redaction_level"] }
    },
    {
      "if": {
        "properties": {
          "source": { "const": "publedge-original-draft" },
          "status": { "not": { "const": "proposed" } }
        },
        "required": ["source", "status"]
      },
      "then": { "not": {} }
    },
    {
      "if": {
        "anyOf": [
          { "required": ["withdrawn_date"] },
          { "required": ["withdrawal_reason"] },
          { "required": ["withdrawn_by_instrument"] }
        ]
      },
      "then": {
        "required": ["withdrawn_date", "withdrawal_reason", "withdrawn_by_instrument"]
      }
    }
  ]
}