# DDR-0011: inventory.json Location, Schema, and Versioning

Status: Accepted  
Date: 2025-12-22  
Related ADRs: ADR-0012 (Inventory-Driven API Surface)

## Context

inventory.json is the authoritative implemented API surface. To keep it stable and
maintainable, its location and schema must be explicit, and future changes must be
reviewable.

## Decision

inventory.json will be stored at:

elkm1/elke27_lib/messages/inventory.json

Schema (v1):

- "schema_version": integer (starting at 1)
- "source": object with optional fields describing provenance (doc name, extracted_on)
- "domains": object mapping:
    domain_name (string) -> commands (array of strings)

Optional additions are allowed only if they preserve backward compatibility, such as:
- per-domain notes
- per-command notes
- disabled/experimental markers (future)

Any change to schema_version must be accompanied by code changes that support both
old and new schema versions during a transition period, unless explicitly breaking.

## Rationale

- Makes inventory updates deterministic and reviewable
- Prevents ad-hoc schema drift that breaks tooling and registries
- Enables long-term stability even as docs evolve

## Consequences

- registry.py must validate schema_version and required keys
- inventory.json updates must be intentional and committed
- tooling (generators/tests) must treat inventory.json as canonical input
