{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://github.com/welkaim/ea-codex/schemas/v1/policy-constraint.json",
  "title": "PolicyConstraint",
  "description": "Typed enterprise or regulatory policy that constrains decisions and specifications. Distinct from ArchitecturePrinciple (which guides) and TechnologyStandard (which catalogues approved patterns): a PolicyConstraint is an enforceable rule sourced from regulation, internal compliance, or contractual obligation. The chain Intent -> Policy -> Decision -> Specification -> Control -> Evidence requires Policy as a typed link. Without it, policies live as embedded fields and string references, and the chain cannot be traversed end-to-end. Introduced in Chapter 6.",
  "type": "object",
  "required": ["apiVersion", "kind", "metadata", "spec"],
  "properties": {
    "apiVersion": { "$ref": "_common.json#/$defs/apiVersion" },
    "kind": { "type": "string", "const": "PolicyConstraint" },
    "metadata": { "$ref": "_common.json#/$defs/metadata" },
    "spec": {
      "type": "object",
      "required": ["statement", "source", "appliesWhen"],
      "properties": {
        "statement": {
          "type": "string",
          "minLength": 20,
          "description": "The constraint itself, normative, expressed as a single rule. Should compile cleanly into a fitness function or runtime check."
        },
        "source": {
          "type": "object",
          "required": ["type"],
          "description": "Where the policy originates. Determines who can change it and what evidence applies.",
          "properties": {
            "type": {
              "type": "string",
              "enum": ["regulation", "internal-compliance", "contractual", "vendor-policy", "ethical-charter"]
            },
            "externalRef": {
              "type": "string",
              "description": "Pointer to the source document or registry entry (e.g., 'gxp-policy:PV-014', 'ema-gvp:module-vi', 'sap-note:3439186')."
            },
            "jurisdiction": {
              "type": "string",
              "description": "Jurisdiction the policy applies in (e.g., 'EU', 'US', 'JP', 'global')."
            }
          },
          "additionalProperties": true
        },
        "appliesWhen": {
          "type": "object",
          "description": "Scope of applicability. The constraint is in force only when one or more of these conditions are true.",
          "properties": {
            "capabilityRefs": {
              "type": "array",
              "description": "Free-text references to business capabilities the constraint applies to. Capability identifiers live in the EA platform's capability map.",
              "items": { "type": "string" }
            },
            "businessObjectRefs": {
              "type": "array",
              "items": { "$ref": "_common.json#/$defs/identifier" },
              "description": "BusinessObject identifiers the constraint applies to."
            },
            "dataSensitivity": {
              "type": "array",
              "items": { "type": "string" },
              "description": "Sensitivity tags that trigger the constraint (e.g., 'phi', 'pii', 'financial')."
            },
            "agentDelegationLevels": {
              "type": "array",
              "items": { "$ref": "_common.json#/$defs/delegationLevel" },
              "description": "Agent delegation levels at which the constraint applies."
            }
          },
          "additionalProperties": true
        },
        "enforcement": {
          "type": "object",
          "description": "How the constraint is enforced. The Codex requires at least one enforcement reference for an approved policy.",
          "properties": {
            "controlRefs": {
              "type": "array",
              "items": { "$ref": "_common.json#/$defs/identifier" },
              "description": "FitnessFunction or RegoPackage identifiers that enforce the policy."
            },
            "humanReviewRequired": { "type": "boolean" },
            "blockingOnViolation": {
              "type": "boolean",
              "description": "Whether a detected violation blocks the action or merely logs an exception."
            }
          },
          "additionalProperties": true
        },
        "exceptions": {
          "type": "string",
          "description": "Conditions under which exceptions may be granted. Should reference a DecisionRecord with a sunset date and a named risk owner."
        },
        "supersedes": {
          "type": "string",
          "description": "Identifier of an earlier policy this one replaces. Allows policy evolution without losing audit trail."
        },
        "relatedPrinciples": {
          "type": "array",
          "description": "Architecture principles the policy realizes or constrains.",
          "items": { "$ref": "_common.json#/$defs/identifier" }
        }
      },
      "additionalProperties": true
    }
  },
  "additionalProperties": false
}