{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://huggingface.co/flowxai/semantic-mapper/inference_contract/schema_mapper_v1.json",
  "title": "FlowX Semantic Mapper output (schema_mapper_v1)",
  "description": "The single JSON object the Semantic Mapper emits for one regulatory/legal text chunk. Three facets: structural, semantic, governance. Prompt version mapper_sys_v1.",
  "type": "object",
  "additionalProperties": false,
  "required": ["structural", "semantic", "governance"],
  "properties": {
    "structural": {
      "type": "object",
      "description": "Where the chunk sits in its source document.",
      "additionalProperties": false,
      "required": ["source_id", "hierarchy", "document_type"],
      "properties": {
        "source_id": {
          "type": "string",
          "description": "Stable identifier for the chunk, typically an uppercased normalization of the citation path (e.g. US_CA_INS_790_03_h_2)."
        },
        "hierarchy": {
          "type": "array",
          "description": "Ordered flat array of alternating [level, value] pairs from the outermost container down to the leaf (e.g. [\"state_code\",\"california_insurance_code\",\"section\",\"790.03\",\"subdivision\",\"h\",\"paragraph\",\"2\"]).",
          "items": { "type": "string" },
          "minItems": 2
        },
        "document_type": {
          "type": "string",
          "description": "Snake_case document class, e.g. state_insurance_code, eu_regulation, federal_regulation, labor_code, adr_agreement."
        }
      }
    },
    "semantic": {
      "type": "object",
      "description": "What the chunk is about.",
      "additionalProperties": false,
      "required": ["domain_tags", "concepts", "entities"],
      "properties": {
        "domain_tags": {
          "type": "array",
          "description": "Free snake_case topic tags (open vocabulary). Less consistent than concepts by design.",
          "items": { "type": "string" }
        },
        "concepts": {
          "type": "array",
          "description": "Concept ids drawn from the 252-concept controlled taxonomy (concept_taxonomy.yaml, shipped at repo root). Values SHOULD be in-vocabulary; out-of-vocabulary ids are treated as errors by downstream consumers.",
          "items": { "type": "string" }
        },
        "entities": {
          "type": "object",
          "description": "The core actor/action/object triple plus a constraint map.",
          "additionalProperties": false,
          "required": ["actor", "action", "object", "constraint"],
          "properties": {
            "actor": {
              "type": "string",
              "description": "Who the obligation/right falls on (e.g. insurer, employer, carrier, credit_institution)."
            },
            "action": {
              "type": "string",
              "description": "What must/may/must-not be done (verb phrase)."
            },
            "object": {
              "type": "string",
              "description": "What the action is performed on (e.g. claim_communication, personal_data, hazmat_package)."
            },
            "constraint": {
              "type": "object",
              "description": "Free key/value map of qualifying conditions (e.g. {\"condition\":\"reasonably_prompt\"}, {\"deadline_days\":\"30\"}). Keys and values are snake_case strings.",
              "additionalProperties": { "type": "string" }
            }
          }
        }
      }
    },
    "governance": {
      "type": "object",
      "description": "How the chunk maps to FlowX policy and escalation.",
      "additionalProperties": false,
      "required": ["policy_references", "escalation_trigger"],
      "properties": {
        "policy_references": {
          "type": "array",
          "description": "Policy ids in the form PDP.<domain>.<rule> (e.g. PDP.insurance.claims_settlement).",
          "items": {
            "type": "string",
            "pattern": "^PDP\\.[a-z_]+\\.[a-z0-9_]+$"
          }
        },
        "escalation_trigger": {
          "type": "string",
          "description": "A single guard clause in the form 'if <condition> THEN escalate' consumed downstream by the Sentinel Gate."
        }
      }
    }
  }
}