{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id":     "docs/runtime/feature-flags-service/override_store_schema.json",
  "title":   "Feature Flag Override Store · Phase 2b",
  "description": "JSON-Schema for docs/runtime/feature-flags-service/override_examples.json (A-owned · file-backed · read-only scaffold). This same shape is the contract Phase 2c will persist in Postgres. approval_ref is display-only in Phase 2b — no verification against an approval store yet.",
  "type": "object",
  "required": ["schema_version", "baseline", "owner", "overrides"],
  "properties": {
    "schema_version": { "type": "string" },
    "baseline":       { "type": "string" },
    "phase":          { "type": "string" },
    "updated_at":     { "type": "string", "format": "date" },
    "owner":          { "type": "string" },
    "honest_note":    { "type": "string" },
    "precedence_note":{ "type": "string" },
    "overrides": {
      "type": "array",
      "items": { "$ref": "#/definitions/override_row" }
    }
  },
  "definitions": {
    "override_row": {
      "type": "object",
      "required": ["id", "scope", "flag_key", "value", "created_at", "created_by", "source", "rationale"],
      "properties": {
        "id": {
          "type": "string",
          "pattern": "^ovr-[a-zA-Z0-9._-]+$",
          "description": "Unique override id · prefix 'ovr-' · kebab/dot/underscore only"
        },
        "scope": {
          "type": "string",
          "enum": ["tenant", "user"],
          "description": "user rows carry both tenant_id and user_id · tenant rows carry only tenant_id"
        },
        "flag_key": {
          "type": "string",
          "description": "must exist in registry.flags[].key · template keys (tenant.<tenant_id>.*) allowed"
        },
        "tenant_id": {
          "type": ["string", "null"],
          "description": "tenant scope id · null only when flag is platform-global"
        },
        "user_id": {
          "type": ["string", "null"],
          "description": "required when scope='user' · null when scope='tenant'"
        },
        "value": {
          "description": "override value · MUST match registry.flags[key].type (bool / string / number)"
        },
        "expires_at": {
          "type": ["string", "null"],
          "format": "date-time",
          "description": "ISO-8601 · null = non-expiring · engine treats past values as absent"
        },
        "approval_ref": {
          "type": ["string", "null"],
          "description": "approval_queue id · display-only in Phase 2b · not verified"
        },
        "created_at": { "type": "string", "format": "date-time" },
        "created_by": { "type": "string" },
        "source": {
          "type": "string",
          "enum": ["manual", "api", "migration", "demo-seed"]
        },
        "rationale": {
          "type": "string",
          "minLength": 1,
          "description": "non-empty free text · human readable"
        }
      },
      "allOf": [
        {
          "if":   { "properties": { "scope": { "const": "user" } } },
          "then": { "required": ["user_id", "tenant_id"] }
        },
        {
          "if":   { "properties": { "scope": { "const": "tenant" } } },
          "then": { "required": ["tenant_id"], "properties": { "user_id": { "type": "null" } } }
        }
      ]
    }
  }
}