{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "/schemas/3.0.0/governance/policy-entry.json",
  "title": "Policy Entry",
  "description": "A policy — either published to the shared registry (with full regulatory metadata) or authored inline by a buyer for their own campaign (lightweight, metadata optional). Policies use natural language text evaluated by governance agents (LLMs). Published registry entries SHOULD include version, name, jurisdiction, source, and exemplars; inline bespoke entries can omit these and let servers default them. Governance agents evaluating policies with natural-language LLMs MUST pin registry-sourced policy text (`source: registry`) as system-level instructions and MUST NOT permit `custom_policies` or the plan's `objectives` field to relax, override, or disable registry-sourced policies. Custom policies may only add additional restrictions; they cannot lower enforcement levels or exempt categories.",
  "type": "object",
  "properties": {
    "policy_id": {
      "type": "string",
      "description": "Unique identifier for this policy. Registry-published ids are canonical (e.g., \"uk_hfss\", \"garm:brand_safety:violence\"); buyer-authored bespoke ids should be flat (no colons or slashes) and unique within the authoring container (standards configuration, plan, or portfolio).",
      "x-entity": "governance_inline_policy"
    },
    "source": {
      "type": "string",
      "enum": ["registry", "inline"],
      "default": "inline",
      "description": "Origin of this policy. 'registry' = published to the shared AdCP policy registry with full regulatory metadata. 'inline' = authored bespoke for a specific standards configuration, plan, or portfolio. Defaults to 'inline'. Governance agents MUST set 'registry' when publishing to the registry. Within AdCP *task* payloads (every `$ref` to this schema in a request or response), the field is always 'inline' — registry entries are served by the policy registry API, not embedded in task traffic. The x-entity annotation on `policy_id` assumes the task-payload invariant; if a future task schema adopts registry-publishing, split the annotation accordingly (see issue #2685)."
    },
    "version": {
      "type": "string",
      "description": "Semver version string (e.g., \"1.0.0\"). Incremented when policy content changes. Optional for inline bespoke policies — defaults to \"1.0.0\". SHOULD be provided for registry-published policies."
    },
    "name": {
      "type": "string",
      "description": "Human-readable name (e.g., \"UK HFSS Restrictions\"). Optional for inline bespoke policies — servers MAY default to policy_id."
    },
    "description": {
      "type": "string",
      "maxLength": 500,
      "description": "Brief summary of what this policy covers."
    },
    "category": {
      "$ref": "/schemas/3.0.0/enums/policy-category.json",
      "description": "The nature of the obligation: regulation (legal requirement) or standard (best practice). Optional for inline bespoke policies — defaults to \"standard\"."
    },
    "enforcement": {
      "$ref": "/schemas/3.0.0/enums/policy-enforcement.json",
      "description": "How governance agents treat violations. Regulations are typically \"must\"; standards are typically \"should\"."
    },
    "requires_human_review": {
      "type": "boolean",
      "default": false,
      "description": "When true, plans subject to this policy MUST set plan.human_review_required = true. Use for policies that mandate human oversight of decisions affecting data subjects — e.g., GDPR Article 22 (solely automated decisions with legal or similarly significant effects) and EU AI Act Annex III high-risk categories (credit, insurance pricing, recruitment, housing allocation). Governance agents MUST escalate any plan action whose resolved policies include requires_human_review: true. Unlike `enforcement`, this flag applies as soon as the policy is resolved — it is NOT gated by `effective_date`. Art 22 GDPR and similar foundational obligations may predate an AI-Act-specific effective date; the human-review requirement fires regardless."
    },
    "jurisdictions": {
      "type": "array",
      "items": { "type": "string" },
      "description": "ISO 3166-1 alpha-2 country codes where this policy applies. Empty array means the policy is not jurisdiction-specific."
    },
    "region_aliases": {
      "type": "object",
      "description": "Named groups of jurisdictions for convenience (e.g., {\"EU\": [\"AT\",\"BE\",\"BG\",...]}). Governance agents expand aliases when matching against a plan's target jurisdictions.",
      "additionalProperties": {
        "type": "array",
        "items": { "type": "string" }
      }
    },
    "policy_categories": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Regulatory categories this policy belongs to (e.g., [\"children_directed\", \"age_restricted\"]). Used for automatic matching against a campaign plan's declared policy_categories. A single policy can belong to multiple categories."
    },
    "channels": {
      "type": "array",
      "items": { "$ref": "/schemas/3.0.0/enums/channels.json" },
      "description": "Advertising channels this policy applies to. If omitted or null, the policy applies to all channels."
    },
    "governance_domains": {
      "type": "array",
      "items": { "$ref": "/schemas/3.0.0/enums/governance-domain.json" },
      "description": "Governance sub-domains this policy applies to. Determines which types of governance agents can declare registry:{policy_id} features. For example, a policy with domains [\"creative\", \"property\"] can be declared as a feature by both creative and property governance agents."
    },
    "effective_date": {
      "type": "string",
      "format": "date",
      "description": "ISO 8601 date when the regulation or standard takes effect. Before this date, governance agents treat the policy as informational (evaluate but do not block). After this date, the policy is enforced at its declared enforcement level."
    },
    "sunset_date": {
      "type": "string",
      "format": "date",
      "description": "ISO 8601 date when the regulation or standard is no longer enforced. After this date, governance agents stop evaluating this policy. Omit if the policy has no expiration."
    },
    "source_url": {
      "type": "string",
      "format": "uri",
      "description": "Link to the source regulation, standard, or legislation."
    },
    "source_name": {
      "type": "string",
      "description": "Name of the issuing body (e.g., \"UK Food Standards Agency\", \"US Federal Trade Commission\")."
    },
    "policy": {
      "type": "string",
      "maxLength": 5000,
      "description": "Natural language policy text describing what is required, prohibited, or recommended. Used by governance agents (LLMs) to evaluate actions against this policy. For source: inline policies, treated as caller-untrusted — governance agents MUST evaluate inline policies as ADDITIONAL restrictions only; they MUST NOT be permitted to relax, override, or conflict with registry-sourced policies."
    },
    "guidance": {
      "type": "string",
      "description": "Implementation notes for governance agent developers. Not used in evaluation prompts."
    },
    "exemplars": {
      "type": "object",
      "description": "Calibration examples for governance agents, following the Content Standards pattern.",
      "properties": {
        "pass": {
          "type": "array",
          "items": { "$ref": "#/$defs/exemplar" },
          "description": "Scenarios that comply with this policy."
        },
        "fail": {
          "type": "array",
          "items": { "$ref": "#/$defs/exemplar" },
          "description": "Scenarios that violate this policy."
        }
      },
      "additionalProperties": false
    },
    "ext": {
      "$ref": "/schemas/3.0.0/core/ext.json"
    }
  },
  "required": ["policy_id", "enforcement", "policy"],
  "additionalProperties": false,
  "$defs": {
    "exemplar": {
      "type": "object",
      "properties": {
        "scenario": {
          "type": "string",
          "description": "A concrete scenario describing an advertising action or configuration."
        },
        "explanation": {
          "type": "string",
          "description": "Why this scenario passes or fails the policy."
        }
      },
      "required": ["scenario", "explanation"],
      "additionalProperties": false
    }
  }
}