---
schema_version: 1
id: RAC-KTQ63DW5R1RP
type: requirement
---
# RAC v0.5.2 — Schema Reference

## Context

v0.5.0 introduced `rac improve`, allowing RAC to identify missing sections in Requirement artifacts.

v0.5.1 extended improvement guidance by making artifact schemas self-describing through:

* Section descriptions
* Section guidance
* Schema-driven templates

However, users currently need an existing artifact before RAC can explain what the artifact should contain.

This creates a gap for users who want to create a new artifact from scratch or understand the full structure of a supported artifact type.

v0.5.2 introduces a new schema reference command:

```bash
rac schema
```

This command exposes RAC's artifact schemas directly through the CLI.

Schema templates are structural starters. They should pass RAC validation, but
users remain responsible for replacing TODO content with meaningful product
knowledge.

---

## Problem

RAC schemas now contain useful information:

* Required sections
* Recommended sections
* Optional sections
* Descriptions
* Guidance
* Metadata values

However, this information is only indirectly accessible through commands such as:

```bash
rac inspect
rac validate
rac improve
```

Users need a direct way to answer:

```text
What should this artifact look like?
```

without first creating a file.

---

## Goals

Introduce:

```bash
rac schema
```

to expose supported artifact schemas directly.

Support:

* Listing available schemas
* Human-readable schema reference
* JSON schema reference
* Full Markdown starter templates

while remaining:

* Read-only
* Deterministic
* AI-optional
* File-free
* Stdout-only

---

## Requirements

### REQ-001 — List Supported Schemas

The system shall support:

```bash
rac schema --list
```

and list all supported artifact schemas.

Example:

```text
Available Schemas:
- requirement
- decision
```

---

The system shall also support:

```bash
rac schema --list --json
```

and return supported schemas in `ARTIFACT_SPECS` order.

Example:

```json
{
  "schemas": [
    "requirement",
    "decision"
  ]
}
```

---

### REQ-002 — Display Schema Reference

The system shall support:

```bash
rac schema requirement
```

and display the schema in a human-readable format.

The output shall include:

* Artifact type
* Required sections
* Recommended sections
* Optional sections
* Section descriptions
* Section guidance
* Metadata fields where applicable

---

### REQ-003 — JSON Output

The system shall support:

```bash
rac schema requirement --json
```

and return a structured representation of the schema.

Example:

```json
{
  "type": "requirement",
  "required": [
    "problem",
    "requirements"
  ],
  "recommended": [
    "success_metrics",
    "risks",
    "assumptions"
  ],
  "optional": [],
  "descriptions": {
    "problem": "The problem being solved."
  },
  "guidance": {
    "problem": [
      "Who experiences this problem?",
      "Why does it matter?"
    ]
  },
  "metadata": {}
}
```

---

### REQ-004 — Template Output

The system shall support:

```bash
rac schema requirement --template
```

and emit a full Markdown starter template for the requested artifact type.

Example:

```markdown
# Title

## Problem

TODO: describe the problem being solved and who experiences it.

<!-- Who experiences this problem? -->
<!-- Why does it matter? -->

## Requirements

- [REQ-001] TODO: describe a required system behaviour.

<!-- What must the system do? -->
<!-- Are these testable [REQ-NNN] statements? -->

## Success Metrics

TODO: describe how success will be measured.

<!-- How will success be measured? -->

## Risks

TODO: describe implementation, delivery, operational, or adoption risks.

<!-- What could prevent successful delivery? -->

## Assumptions

TODO: describe conditions assumed to be true.

<!-- What must be true for this requirement to hold? -->
```

Generated templates shall be structurally valid RAC artifacts. They are not
semantically complete artifacts.

---

### REQ-005 — Decision Schema Support

The system shall support:

```bash
rac schema decision
```

and expose the Decision artifact schema.

The Decision schema shall include:

* Required sections
* Recommended sections
* Optional sections
* Descriptions
* Guidance
* Supported metadata values

Metadata values shall include supported values for:

* Status
* Category

---

### REQ-006 — Unknown Schema Handling

Unknown schema names shall produce an actionable error.

Example:

```bash
rac schema roadmap
```

Output:

```text
Unknown schema: roadmap

Available schemas:
- requirement
- decision
```

The command shall exit with code `2`.

---

### REQ-007 — Output Mode Exclusivity

The following output modes shall be mutually exclusive:

* Human-readable schema reference
* JSON schema reference
* Markdown template output

Examples:

```bash
rac schema requirement
rac schema requirement --json
rac schema requirement --template
```

---

### REQ-008 — Schema Source of Truth

`rac schema` shall consume `ArtifactSpec` directly.

It shall not duplicate schema definitions in CLI code or output rendering code.

---

### REQ-009 — Stdin Validation Compatibility

The system shall support:

```bash
rac validate -
```

to validate Markdown content from stdin.

This enables schema-generated templates to be validated through standard shell
pipelines.

Example:

```bash
rac schema requirement --template | rac validate -
```

The behavior shall match validation of equivalent file-based Markdown input.

---

## Non-Goals

### File Inspection

Not:

```bash
rac schema file.md
```

Schema reference operates on artifact types, not artifact files.

---

### Validation

Not:

```bash
rac schema requirement --validate
```

Validation remains the responsibility of:

```bash
rac validate
```

`rac validate -` is a narrow stdin compatibility improvement. It does not add
schema validation behavior to `rac schema`.

### Semantic Completeness

Not:

```text
Generated templates are meaningful finished artifacts.
```

Generated templates are structurally valid starter documents; users remain
responsible for replacing TODO content with meaningful product knowledge.

---

### Improvement Analysis

Not:

```bash
rac schema requirement --missing file.md
```

Missing-section analysis remains the responsibility of:

```bash
rac improve
```

---

### AI Guidance

Not:

```text
Generate a better schema
```

or:

```text
Suggest better requirements
```

All schema information is deterministic and defined in `ArtifactSpec`.

---

### Custom Schemas

Not:

```bash
rac schema custom.yaml
```

Custom or user-defined schemas are out of scope for v0.5.2.

---

## Success Metrics

### Functional

* Users can list supported schemas.
* Users can inspect a full schema without creating a file.
* Users can generate a starter template for supported artifact types.
* JSON output exposes the same schema information as human output.
* Unknown schema names fail clearly with actionable guidance.
* Generated templates pass RAC validation through stdin pipelines.

### Product

A user can create a new RAC-compliant Requirement or Decision artifact using only:

```bash
rac schema requirement --template
```

or:

```bash
rac schema decision --template
```

---

## Acceptance Criteria

```bash
rac schema --list
```

lists supported schemas.

```bash
rac schema --list --json
```

returns supported schemas in machine-readable form.

```bash
rac schema requirement
```

displays required, recommended, and optional sections.

```bash
rac schema decision
```

displays Decision metadata fields and supported values.

```bash
rac schema requirement --json
```

returns a structured schema object.

```bash
rac schema decision --json
```

returns Decision schema metadata values.

```bash
rac schema requirement --template
```

emits a complete Markdown starter template.

```bash
rac schema decision --template
```

emits a complete Markdown starter template for a Decision artifact.

```bash
rac schema requirement --template | rac validate -
```

passes.

```bash
rac schema decision --template | rac validate -
```

passes.

```bash
rac schema roadmap
```

fails with exit code `2` and lists available schemas.

No files are modified.

No AI services are required.

---

## Future Considerations

Future releases may extend `rac schema` to support:

* Roadmap schemas
* Prompt schemas
* Meeting schemas
* Custom schemas
* Schema versioning
* External schema export formats

When new artifact schemas are added to RAC, they should automatically become available through `rac schema` if they are registered in `ArtifactSpec`.
