design-schemas

---
name: design-schemas
description: Use when a schema needs to be designed, reviewed, simplified, or modified, including but not limited to JSON, YAML, and Markdown schemas.
license: MIT
---

# Design Schemas

Produce the smallest schema that fully serves current readers, writers, decisions, validators, safety boundaries, and committed contracts. Treat background as context, not as a field list.

## Preconditions

Identify before designing:

- who or what writes the data;
- who or what reads it;
- what action, decision, validation, storage, or transfer each consumer performs;
- whether the target is Agent-facing, program-facing, or contains a specific boundary between both;
- whether schema changes are cheap and coordinated or have concrete high migration cost.

If the consumer class, current consumption, or relevant change cost is unknown, ask only the focused questions needed to establish them. Do not emit a speculative “production-ready” schema while these facts are missing.

## Workflow

### 1. Classify the contract

Use these meanings:

- **Agent-facing:** an Agent reads or updates working memory, a blackboard, a handoff card, or rule state and uses it to choose an action. Prefer human-readable, forgiving representations.
- **Program-facing:** deterministic code parses, validates, stores, transmits, or exposes the data as a contract. Preserve every requirement of its current machine consumers and safety boundary.
- **Mixed:** an Agent edits or reasons about data that crosses a named machine boundary. Apply Agent-facing restraint outside the boundary and program-facing rigor at it; do not call the whole artifact program-facing merely because a script touches the file.

Continue only when the classification and current consumers are explicit.

### 2. Establish field eligibility

Start with no fields. Add a business field only when at least one current fact can be named:

- a reader uses it to change an action or decision;
- a writer must preserve information that cannot be recovered when needed;
- a program parses, validates, stores, routes, or transmits it;
- a current safety boundary or committed contract requires it.

For each proposed field, be able to state its writer, consumer, and effect. Omit it when its only reason is completeness, professionalism, future expansion, possible debugging, generic auditability, observability, multi-Agent readiness, or a noun mentioned in the background.

Do not encode a negated non-requirement. “Not a compliance record” excludes compliance structure; it does not justify `compliance_record: false`.

Continue when every surviving business field has current consumer evidence.

### 3. Choose the least structured adequate representation

For Agent-facing state:

- Prefer shallow Markdown when headings and free text are enough for reading and replacement.
- Prefer shallow YAML or JSON when stable keys materially help repeated updates, selection, or handoff.
- Keep a description or instruction as one scalar unless its parts are independently read, written, validated, or acted on.
- Do not add IDs, versions, update timestamps, lifecycle state, categories, references, ownership types, empty metadata, or nested containers without field-specific evidence.
- Retain clear semantic names. Minimal means minimum unsupported structure, not minimum characters.

For program-facing state:

- Use the requested serialization and the validation structure its real parser or protocol needs.
- Preserve required types, cardinality, constraints, identifiers, security controls, and transport or storage semantics.
- Distinguish representation syntax such as JSON Schema's `type` and `properties` from business fields; minimize unsupported business fields without deleting necessary schema mechanics.
- Subject optional annotations and schema-identity metadata such as `$id`, `title`, `default`, `examples`, and `deprecated` to the same consumer test. Add them only when a named registry, generator, validator, user, or requested documentation consumes them; familiarity or convention alone is not evidence.

Objectify a scalar only when at least two subfields have separate current consumers or constraints. For example, keep `next_action: "Move items to the spare freezer"` instead of inventing `instruction` and `notBefore` unless separate code or decisions use both.

### 4. Apply the compatibility gate

Treat compatibility as a requirement only when concrete evidence shows schema change, migration, or protocol coordination is very expensive. Qualifying evidence can include independently deployed external producers and consumers, persisted historical data that must remain readable, a long non-atomic migration, or an existing requirement for multiple versions to coexist.

Cheap local configuration, one same-repository script, hypothetical future clients, and generic “production readiness” do not pass this gate.

When the gate passes, add only the smallest compatibility mechanism that addresses the named cost. Trace each version discriminator, fallback, alias, or migration field to a specific consumer or migration constraint. When cost evidence is missing, clarify instead of assuming either cheap change or enterprise compatibility.

### 5. Produce or review the schema

For a new schema, add eligible fields from the empty set and stop when all current consumption is satisfied.

For an existing schema, mark each business field or object as:

- **keep:** a current consumer, safety boundary, or costly contract requires it;
- **remove:** it is unconsumed, derivable when needed, persistently empty, duplicate, or future-only;
- **clarify:** removal could affect an unidentified machine consumer or migration boundary.

Return the requested schema plus only the explanation needed to expose material consumer decisions. In a review, state removals and the evidence for retained non-obvious structure.

### 6. Verify before finishing

Audit the result:

1. List the business leaf fields and compare them with current consumed information.
2. Confirm that every object boundary has independently consumed or constrained children.
3. Confirm that background systems, exclusions, and hypothetical future needs did not become fields.
4. For Agent-facing state, confirm that free text was not needlessly converted into a rule language.
5. For program-facing state, confirm that current parsers, validation, safety, storage, transport, and public commitments still work.
6. Confirm that every compatibility element passed the high-cost gate with specific evidence.

If an item fails, remove or flatten the unsupported structure and repeat the audit. If evidence is missing rather than disproven, ask before changing the boundary.

## Finish

Complete only when the schema is sufficient for all named current consumers, contains no unsupported business field or nesting, and any compatibility mechanism is tied to concrete high migration cost. Otherwise stop with the smallest focused clarification request.