config-atlas/docs/configuration-surface-schema.md

Configuration Surface Schema

Status: draft Updated: 2026-06-26 Repo: config-atlas Schema: ../schemas/surface-entry.schema.json Related: canon-mapping.md, ../specs/ProductRequirementsDocument.md §7/§10, ../specs/ArchitectureBlueprint.md §3

A configuration surface is a bounded, named place where configuration is defined, read, or overridden. Each surface is one markdown file in registry/surfaces/ whose YAML frontmatter validates against schemas/surface-entry.schema.json; the markdown body holds prose (meaning, precedence notes, gotchas).

The atlas stores the map: where a surface lives, who owns it, its kind, scope, and source links. It never stores live configuration values and never stores secret values (PRD NFR-2, NFR-4). additionalProperties: false throughout the schema prevents an entry from sneaking a value field anywhere.

Fields

Field	Required	Meaning
id	yes	Stable id surface.<domain>.<system>.<name> (lowercase, dashes).
name	yes	Human-readable name.
kind	yes	Closed taxonomy (below). Drives kind-separation.
summary	yes	One-line description.
owner	yes	Team/agent identity, resolved against domain-tree. Not a person.
status	yes	draft | active | deprecated.
scope	yes	allowed_layers (subset of the layer ordering) + default_layer.
mutability	yes	Delivery stage / blast radius (below).
security_class	yes	operational | sensitive | secret-ref | policy.
schema	no	The contract (type/default/min/max/validator) — metadata, not a live value.
sources	yes	Canonical sources by reference, each with a layer role. Never inlines a value.
relations	no	consumed_by, overrides, depends_on_secret (refs only), related_to.
evidence	no	last_seen, discovery_method, change_log_ref.

kind taxonomy

app-config, deploy-config, secret-ref, feature-flag, policy, tenant-config, infra-state, runtime-override. Secrets, flags, and infra-state are never treated as ordinary config. A feature-flag surface links to a feature-control key (via a sources[].role: feature-control-key) and contains no evaluation logic. A secret-ref surface references a secret by id/path only.

mutability classes

build-time, deploy-time, startup-time, hot-reloadable, per-request, emergency. Prevents treating structural config like a harmless flag.

Scope / layer ordering (L0–L9)

allowed_layers and default_layer draw from the shared scope vocabulary — an ordering, not a new set of names (aligned to ITC-LAND/ITC-ORG and feature-control EvaluationScope; see canon-mapping.md):

L0 product-default   L5 installation
L1 company           L6 tenant
L2 platform          L7 group
L3 environment       L8 user / agent
L4 region            L9 emergency

"More specific wins" by default; higher layers may declare non-overridable guardrails. A surface declares which layers may set it, e.g. allowed_layers: [company, environment, tenant].

Merge rules (explicit — no hidden last-writer-wins)

scalar     more specific layer replaces earlier value
object/map deep merge by key
array/list replace by default; keyed merge only if declared
null       not deletion unless tombstone semantics are defined
secret     never merged into normal config
policy     restrictive rule wins unless explicitly delegated

Resolution of the effective value is out of scope (delegated downstream). The atlas renders only the effective-config path — the ordered override path with owner and validating-schema references (PRD FR-5).

Authoring

1. Copy the example below into registry/surfaces/surface.<domain>.<system>.<name>.md.
2. Fill frontmatter; link sources[] to canonical files (no values, no secrets).
3. Add the row to registry/indexes/surfaces.yaml (ATLAS-WP-0002-T03).
4. Validate (ATLAS-WP-0002-T06): frontmatter against the schema, plus reuse-surface validate --root . and git diff --check.

Example

See ../registry/surfaces/surface.infotech.state-hub.api-config.md — a real, validating entry for the State Hub API configuration surface.