{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/ai-law-tracker-com/json-schema/ai-law-tracker-com-enforcement-matter-schema.json",
  "title": "EnforcementMatter",
  "description": "One enforcement or litigation MATTER: a dispute with an identity that persists as it moves. An agency action with a complaint, a settlement and a final order is one matter here, not three rows.",
  "x-generated": "2026-11-01",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/ai-law-tracker-com-openapi.json#/components/schemas/EnforcementMatter",
  "type": "object",
  "properties": {
    "matter_uid": {
      "type": "string",
      "description": "Stable key for fetching this matter again. AN OPAQUE KEY, NOT A DESCRIPTION — do not render it as a name. It is generated from whatever the ingest could parse and is demonstrably unreliable (one uid names RealPage for what is in fact the DOJ/LivCor consent decree). Read `caption`."
    },
    "caption": {
      "type": "string",
      "description": "The matter as a human should read it. This is its name."
    },
    "jurisdiction_level": {
      "type": "string"
    },
    "jurisdiction_slug": {
      "type": "string"
    },
    "jurisdiction_name": {
      "type": [
        "string",
        "null"
      ]
    },
    "forum_type": {
      "type": "string",
      "description": "See /enforcement/categories."
    },
    "forum_name": {
      "type": [
        "string",
        "null"
      ]
    },
    "matter_type": {
      "type": "string",
      "description": "enforcement_action | civil_litigation | guidance_document | investigation | inquiry_6b. See /enforcement/categories."
    },
    "matter_status": {
      "type": "string"
    },
    "docket_number": {
      "type": [
        "string",
        "null"
      ]
    },
    "agency_code": {
      "type": [
        "string",
        "null"
      ],
      "description": "FTC, DOJ, SEC, CFPB, EEOC, a state AG… Free text, not a closed vocabulary."
    },
    "ai_roles": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "How AI figures in the matter. See the ai_role vocabulary."
    },
    "filed_date": {
      "type": [
        "string",
        "null"
      ],
      "format": "date",
      "description": "The date the SOURCE states the action was filed or opened, verbatim. NEVER our scrape date — that is `first_seen_at`, and confusing the two is the defect this field was rebuilt to remove. Null means the source did not state one; it is never inferred, and `date_source` below names where a non-null value came from."
    },
    "decided_date": {
      "type": [
        "string",
        "null"
      ],
      "format": "date",
      "description": "The date the SOURCE states the matter resolved — settlement announced, consent order entered, final order, judgment. Null when unresolved or unstated."
    },
    "date_source": {
      "type": [
        "string",
        "null"
      ],
      "description": "Which source field `filed_date` was lifted from, e.g. `ftc_case_timeline_oldest_entry`, `cfpb_listing_date_filed`, `tx_ag_listing_meta`, `doj_release_published_meta`. Published so a date can be traced rather than trusted. Always present when filed_date is."
    },
    "closed_date": {
      "type": [
        "string",
        "null"
      ],
      "format": "date"
    },
    "summary": {
      "type": [
        "string",
        "null"
      ],
      "description": "Null on 42 of 91 matters."
    },
    "source_authority": {
      "type": "string"
    },
    "source_url": {
      "type": "string",
      "description": "Where the claim came from. Never withheld at any tier — it is how you check our work."
    },
    "verification": {
      "type": "string",
      "description": "Corroboration level. MEASURED 2026-08-22: every matter currently held is `single_source`, i.e. recorded from ONE official source with no second confirmation. Never withheld at any tier; read it before relying on any claim here."
    },
    "first_seen_at": {
      "type": "string",
      "format": "date-time"
    },
    "last_verified_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "primary_domain_id": {
      "type": "string"
    },
    "primary_domain_label": {
      "type": "string"
    },
    "primary_branch_id": {
      "type": "string"
    },
    "primary_branch_label": {
      "type": "string"
    },
    "domains": {
      "type": "array",
      "items": {
        "type": "object"
      },
      "description": "All assigned subject domains, primary and secondary."
    },
    "is_canonical": {
      "type": "boolean",
      "description": "False when another matter_uid already publishes this same source document."
    },
    "duplicate_of": {
      "type": [
        "string",
        "null"
      ],
      "description": "The matter_uid to read instead. Present only on a non-canonical row."
    },
    "publish_ready": {
      "type": "boolean",
      "description": "Canonical AND its CAPTION is in English. Rows where this is false are served only to a caller licensed for the raw registry."
    },
    "unavailable_fields": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Present only when a DESCRIPTIVE field (forum_name, agency_code or summary) was nulled because it still carries untranslated internal working language. The matter itself is published; only these fields are not. A null WITHOUT this list means the source simply did not state a value."
    },
    "unavailable_reason": {
      "type": "string",
      "description": "Why the fields above are null. Present only alongside unavailable_fields."
    },
    "enforcement_tier": {
      "type": [
        "string",
        "null"
      ],
      "description": "A = an enforcement DECISION (complaint filed, consent order, settlement, civil penalty, judgment, cease-and-desist). B = an enforcement-adjacent SIGNAL (opened investigation, sweep, CID, enforcement advisory, 6(b) study order). NULL means the tier was never assessed — true of every matter recorded before 2026-08-22 — and does NOT mean B. Filter `tier=A` when the question is how many real enforcement decisions exist."
    },
    "ai_basis": {
      "type": "object",
      "description": "WHY this matter is in an AI dataset. `matches` lists each term that fired, the field it fired in, the ai_role it implies, and a VERBATIM excerpt of the source text around it; `method` says whether the agency's own classification was used (e.g. the FTC industry tag \"Technology > Artificial Intelligence\") or only keywords. Published deliberately: it is the citation for the inclusion decision, so the corpus can be audited without re-reading every source."
    },
    "source_absent_fields": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Fields the ingest LOOKED FOR and the source did not state. NOT the same as `unavailable_fields`, which is what WE withheld. This one is the agency's gap; that one is ours."
    },
    "industry_labels": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Sector labels the SOURCE applied, verbatim (FTC industry/topic tags, DOJ ATR \"Industry Code(s)\"). Never inferred from the respondent's name."
    },
    "violation_labels": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Violation types the SOURCE stated, verbatim (FTC \"Enforcement Type\"/\"Type of Action\", DOJ ATR \"Case Violation(s)\"). Never inferred from the conduct described."
    },
    "ingest_lane": {
      "type": [
        "string",
        "null"
      ],
      "description": "Which writer produced the row. Provenance, not classification."
    }
  }
}