---
description: Schema for arc42 architecture documentation. Twelve numbered chapters are required; the quality checklist is recommended.
domain: arc42
schema-id: https://markitect.dev/schemas/arc42/v1.0
status: stable
version: 1.0.0
---

# arc42 Architecture Documentation Schema v1.0.0

## Overview

Validates a single-file arc42 architecture document. Chapters 1–12 must
be present as level-2 headings. Chapter 13 (quality checklist) is
recommended. A first-wave stub may mark unused chapters N/A in the body;
the heading must still exist.

## Usage

```bash
markitect validate docs/architecture/<system>_v0.1.md \
  --schema markitect/schemas/arc42-schema-v1.0.md
```

Catalog id: `arc42-v1`.

## Schema Definition

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://markitect.dev/schemas/arc42/v1.0",
  "title": "arc42 Architecture Documentation Schema",
  "description": "Single-file arc42 document with twelve required chapters",
  "type": "object",
  "properties": {
    "headings": {
      "type": "object",
      "properties": {
        "level_1": {
          "type": "array",
          "description": "Document title",
          "minItems": 1,
          "maxItems": 1
        },
        "level_2": {
          "type": "array",
          "description": "arc42 chapters and optional about/checklist headings",
          "minItems": 12
        }
      },
      "required": ["level_1", "level_2"]
    },
    "paragraphs": {
      "type": "array",
      "minItems": 6
    }
  },
  "required": ["headings", "paragraphs"],
  "x-markitect-sections": {
    "1. Introduction and Goals": {
      "classification": "required",
      "heading_level": 2
    },
    "2. Architecture Constraints": {
      "classification": "required",
      "heading_level": 2
    },
    "3. System Scope and Context": {
      "classification": "required",
      "heading_level": 2
    },
    "4. Solution Strategy": {
      "classification": "required",
      "heading_level": 2
    },
    "5. Building Block View": {
      "classification": "required",
      "heading_level": 2
    },
    "6. Runtime View": {
      "classification": "required",
      "heading_level": 2
    },
    "7. Deployment View": {
      "classification": "required",
      "heading_level": 2
    },
    "8. Cross-Cutting Concepts": {
      "classification": "required",
      "heading_level": 2
    },
    "9. Architecture Decisions": {
      "classification": "required",
      "heading_level": 2
    },
    "10. Quality Requirements": {
      "classification": "required",
      "heading_level": 2
    },
    "11. Risks and Technical Debt": {
      "classification": "required",
      "heading_level": 2
    },
    "12. Glossary": {
      "classification": "required",
      "heading_level": 2
    },
    "13. Best-Practice Requirements & Quality Checklist": {
      "classification": "recommended",
      "heading_level": 2
    }
  }
}
```