config-atlas/schemas/surface-entry.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://config-atlas/schemas/surface-entry.schema.json",
  "title": "Configuration Surface Entry",
  "description": "Schema for the YAML frontmatter of a config-atlas configuration-surface entry (registry/surfaces/*.md). Records the MAP of a configuration surface: where it lives, who owns it, its kind, scope, and source links. It stores metadata and references only -- never live configuration values and never secret values. See docs/configuration-surface-schema.md and docs/canon-mapping.md.",
  "type": "object",
  "additionalProperties": false,
  "required": ["id", "name", "kind", "summary", "owner", "status", "scope", "mutability", "security_class", "sources"],
  "properties": {
    "id": {
      "type": "string",
      "description": "Stable id: surface.<domain>.<system>.<name>",
      "pattern": "^surface\\.[a-z0-9-]+\\.[a-z0-9-]+\\.[a-z0-9-]+$"
    },
    "name": { "type": "string", "minLength": 1 },
    "kind": {
      "type": "string",
      "description": "Closed taxonomy. Drives kind-separation.",
      "enum": ["app-config", "deploy-config", "secret-ref", "feature-flag", "policy", "tenant-config", "infra-state", "runtime-override"]
    },
    "summary": { "type": "string", "minLength": 1 },
    "owner": {
      "type": "string",
      "description": "Team/agent identity, resolved against domain-tree bindings. Not a person.",
      "minLength": 1
    },
    "status": { "type": "string", "enum": ["candidate", "draft", "active", "deprecated"] },
    "scope": {
      "type": "object",
      "additionalProperties": false,
      "required": ["allowed_layers", "default_layer"],
      "properties": {
        "allowed_layers": {
          "type": "array",
          "minItems": 1,
          "uniqueItems": true,
          "items": { "$ref": "#/$defs/layer" }
        },
        "default_layer": { "$ref": "#/$defs/layer" }
      }
    },
    "mutability": {
      "type": "string",
      "description": "How the surface may change (delivery stage / blast radius).",
      "enum": ["build-time", "deploy-time", "startup-time", "hot-reloadable", "per-request", "emergency"]
    },
    "security_class": {
      "type": "string",
      "enum": ["operational", "sensitive", "secret-ref", "policy"]
    },
    "schema": {
      "type": "object",
      "description": "The CONTRACT for the surface (metadata), not a live value. 'default' is the declared product default, treated as contract documentation.",
      "additionalProperties": false,
      "properties": {
        "type": { "type": "string", "enum": ["string", "integer", "number", "boolean", "object", "array", "enum"] },
        "default": {},
        "enum": { "type": "array" },
        "minimum": { "type": "number" },
        "maximum": { "type": "number" },
        "validator": {
          "type": "string",
          "description": "Reference to a JSON Schema / CUE file. A pointer, not an inlined value."
        }
      }
    },
    "sources": {
      "type": "array",
      "description": "Canonical sources, by reference. NEVER inlines a configuration or secret value.",
      "minItems": 1,
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": ["role"],
        "properties": {
          "repo": { "type": "string" },
          "path": { "type": "string" },
          "endpoint": { "type": "string" },
          "role": {
            "type": "string",
            "description": "The layer contribution this source makes, e.g. company-baseline, environment-overlay, feature-control-key."
          }
        },
        "anyOf": [
          { "required": ["path"] },
          { "required": ["endpoint"] }
        ]
      }
    },
    "relations": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "consumed_by": { "$ref": "#/$defs/idlist" },
        "overrides": { "$ref": "#/$defs/idlist" },
        "depends_on_secret": {
          "type": "array",
          "description": "Secret references only -- ids/paths, never values.",
          "items": { "type": "string" }
        },
        "related_to": { "$ref": "#/$defs/idlist" }
      }
    },
    "evidence": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "last_seen": { "type": "string", "format": "date" },
        "discovery_method": { "type": "string" },
        "change_log_ref": { "type": "string" }
      }
    }
  },
  "$defs": {
    "layer": {
      "type": "string",
      "description": "Shared scope vocabulary (L0-L9 ordering, aligned to ITC-LAND/ITC-ORG and feature-control EvaluationScope). NOT a new set of names.",
      "enum": ["product-default", "company", "platform", "environment", "region", "installation", "tenant", "group", "user", "agent", "emergency"]
    },
    "idlist": {
      "type": "array",
      "items": { "type": "string" }
    }
  }
}