markitect-main/markitect/schemas/adr-schema-v1.0.md

schema-id, version, status, domain, description

schema-id	version	status	domain	description
https://markitect.dev/schemas/adr/v1.0	1.0.0	stable	adr	JSON schema for Architecture Decision Records (ADRs) with section classification and content control

Architecture Decision Record Schema v1.0

Overview

This schema defines the structure and validation rules for Architecture Decision Records (ADRs) in MarkiTect's markdown format. It includes comprehensive section classification, content control patterns, and quality guidelines to ensure consistent, high-quality architectural documentation.

Architecture Decision Records are documents that capture important architectural decisions along with their context and consequences. This schema ensures ADRs follow a standardized structure that promotes thorough decision documentation and facilitates future reference.

Features

• Section Classification System: Categorizes ADR sections as required, recommended, optional, discouraged, or improper
• Content Control: Validates content patterns, quality metrics, and structural requirements
• Flexible Section Names: Supports alternative section names (e.g., "OPTIONS CONSIDERED" as alternative to "ALTERNATIVES CONSIDERED")
• Quality Enforcement: Minimum/maximum content requirements for key sections
• Decision Matrix Support: Validates tabular comparison of alternatives
• Date and Status Validation: Enforces proper date formats and status indicators

Section Classifications

Required Sections

• STATUS: Current state of the decision (Proposed, Accepted, Deprecated, Superseded) with date
• CONTEXT: Background information explaining why this decision is needed
  • Requirements (recommended subsection): Specific needs driving the decision
  • Problem Statement (recommended subsection): Clear articulation of the problem
• DECISION: Clear statement of what was decided, starting with "We will"
• ALTERNATIVES CONSIDERED: Options that were evaluated before making the decision
• RATIONALE: Explanation of why this decision was made
  • Must include "Why [Selected]?" subsection
  • Must include "Why Not [Alternative]?" subsections for rejected options
• CONSEQUENCES: Impact of the decision
  • Positive (required subsection): Benefits and advantages
  • Negative (required subsection): Drawbacks and limitations
  • Mitigation Strategies (recommended subsection): How to address negatives
• APPROVAL: Decision approval metadata (who, when, next review)

Recommended Sections

• DECISION MATRIX: Tabular comparison of alternatives with criteria
• IMPLEMENTATION DETAILS: Technical specifications and code examples

Optional Sections

• FUTURE CONSIDERATIONS: Potential enhancements and evolution paths
• REFERENCES: External documentation, specifications, and resources

Discouraged Sections

• DRAFT NOTES: Development notes (should be removed before acceptance)
• OPEN QUESTIONS: Unresolved items (should be resolved before acceptance)

Improper Sections

• INTERNAL_DISCUSSIONS: Internal team debates (must not appear in published ADRs)
• TODO: Development tasks (remove before publication)
• TEMPORARY: Temporary content markers (remove before publication)

Usage

Validating an ADR

markitect validate ADR-001-my-decision.md --schema adr-schema-v1.0

Common Validation Errors

1. Missing Required Sections: Ensure STATUS, CONTEXT, DECISION, ALTERNATIVES CONSIDERED, RATIONALE, CONSEQUENCES, and APPROVAL are present
2. Missing "We will" Statement: DECISION must contain a bold statement starting with "We will"
3. Incomplete Rationale: Must include both "Why [Selected]?" and "Why Not [Alternative]?" subsections
4. Missing Consequence Subsections: Both Positive and Negative subsections required
5. Improper Status Format: STATUS must follow pattern **[Status]** - YYYY-MM-DD

Content Quality Guidelines

STATUS Section

• Format: **[Status]** - YYYY-MM-DD
• Valid statuses: Proposed, Accepted, Deprecated, Superseded
• Example: **Accepted** - 2025-11-10
• Keep concise (3-20 words)

CONTEXT Section

• Explain the background and circumstances
• Describe the business or technical drivers
• Include Requirements subsection for specific needs
• Include Problem Statement subsection for clear problem articulation
• Minimum 100 words for comprehensive context

DECISION Section

• Must start with bold statement: **We will [decision]**
• Be specific and actionable
• Avoid ambiguity
• Example: **We will use IndexedDB for client-side debug log storage**

ALTERNATIVES CONSIDERED Section

• List all options evaluated (minimum 2)
• Include technology/implementation details for each
• Provide sufficient detail for future reviewers
• Minimum 150 words total

DECISION MATRIX Section

• Use markdown table format
• Include evaluation criteria as columns
• Use emoji indicators: ✅ (positive), ⚠️ (caution), ❌ (negative)
• Compare all alternatives systematically

RATIONALE Section

• Include ### Why [Selected Option]? subsection explaining the choice
• Include ### Why Not [Alternative]? subsection(s) for each rejected option
• Provide technical and business justifications
• Minimum 100 words total

IMPLEMENTATION DETAILS Section

• Include code examples with syntax highlighting
• Specify technical configurations
• Document integration points
• Provide sufficient detail for implementation

CONSEQUENCES Section

• Positive subsection: List benefits and advantages
• Negative subsection: List drawbacks and limitations
• Mitigation Strategies subsection: Address how negatives will be handled
• Minimum 50 words total
• Be honest about trade-offs

APPROVAL Section

• Include: Decided by, Date, Context, Next Review
• Use ISO 8601 date format (YYYY-MM-DD)
• Specify review period for periodic reassessment

Filename Convention

ADR files must follow this naming pattern:

ADR-[0-9]{3}-[kebab-case-title].md

Examples:

• ADR-001-client-side-debug-storage.md
• ADR-002-robustness-principle-for-production-use.md

Schema Definition

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://markitect.dev/schemas/adr/v1.0",
  "title": "Architecture Decision Record Schema with Classifications",
  "description": "JSON schema for Architecture Decision Records (ADRs) with section classification and content control",
  "version": "1.0.0",
  "x-markitect-sections": {
    "Status": {
      "classification": "required",
      "heading_level": 2,
      "position": "after_title",
      "content_instruction": "Current state of the decision (Proposed, Accepted, Deprecated, Superseded) with ISO 8601 date",
      "min_paragraphs": 1,
      "max_paragraphs": 1,
      "error_message": "Status section is mandatory for all ADRs to track decision lifecycle"
    },
    "Context": {
      "classification": "required",
      "heading_level": 2,
      "content_instruction": "Background information explaining why this decision is needed, including business and technical drivers",
      "min_paragraphs": 2,
      "max_paragraphs": 20,
      "subsections": {
        "Requirements": {
          "classification": "recommended",
          "heading_level": 3,
          "content_instruction": "Specific needs and requirements driving this decision"
        },
        "Problem Statement": {
          "classification": "recommended",
          "heading_level": 3,
          "content_instruction": "Clear articulation of the problem being solved"
        }
      },
      "error_message": "Context section is mandatory to document the circumstances requiring a decision"
    },
    "Decision": {
      "classification": "required",
      "heading_level": 2,
      "content_instruction": "Clear statement of what was decided, starting with bold 'We will' statement",
      "min_paragraphs": 1,
      "max_paragraphs": 5,
      "error_message": "Decision section is mandatory to explicitly state what was decided"
    },
    "Alternatives Considered": {
      "classification": "required",
      "heading_level": 2,
      "alternatives": ["Options Considered", "Alternatives", "Options Evaluated"],
      "content_instruction": "List and describe all options that were evaluated, including technical details",
      "min_paragraphs": 2,
      "max_paragraphs": 30,
      "error_message": "Alternatives Considered section is mandatory to document the decision-making process"
    },
    "Decision Matrix": {
      "classification": "recommended",
      "heading_level": 2,
      "alternatives": ["Comparison Matrix", "Evaluation Matrix", "Comparison Table"],
      "content_instruction": "Tabular comparison of alternatives using evaluation criteria with emoji indicators",
      "warning_if_missing": "Decision matrices help visualize trade-offs and make the evaluation process transparent"
    },
    "Rationale": {
      "classification": "required",
      "heading_level": 2,
      "content_instruction": "Explanation of why this decision was made, including 'Why [Selected]?' and 'Why Not [Alternative]?' subsections",
      "min_paragraphs": 2,
      "max_paragraphs": 20,
      "subsections": {
        "Why": {
          "classification": "required",
          "heading_level": 3,
          "pattern": "### Why .+\\?",
          "content_instruction": "Explain why the chosen option was selected and why alternatives were rejected"
        }
      },
      "error_message": "Rationale section is mandatory to document the reasoning behind the decision"
    },
    "Implementation Details": {
      "classification": "recommended",
      "heading_level": 2,
      "content_instruction": "Technical specifications, code examples, and implementation guidance",
      "min_paragraphs": 1,
      "max_paragraphs": 30,
      "min_code_blocks": 1,
      "warning_if_missing": "Implementation details help teams execute the decision consistently"
    },
    "Consequences": {
      "classification": "required",
      "heading_level": 2,
      "content_instruction": "Impact of the decision, including positive and negative effects with mitigation strategies",
      "min_paragraphs": 2,
      "max_paragraphs": 20,
      "subsections": {
        "Positive": {
          "classification": "required",
          "heading_level": 3,
          "content_instruction": "Benefits and advantages of this decision"
        },
        "Negative": {
          "classification": "required",
          "heading_level": 3,
          "content_instruction": "Drawbacks, limitations, and trade-offs of this decision"
        },
        "Mitigation Strategies": {
          "classification": "recommended",
          "heading_level": 3,
          "content_instruction": "Approaches to address negative consequences"
        }
      },
      "error_message": "Consequences section is mandatory to understand the full impact of the decision"
    },
    "Future Considerations": {
      "classification": "optional",
      "heading_level": 2,
      "content_instruction": "Potential enhancements, evolution paths, and future review topics"
    },
    "References": {
      "classification": "optional",
      "heading_level": 2,
      "content_instruction": "External documentation, specifications, articles, and resources that informed the decision"
    },
    "Approval": {
      "classification": "required",
      "heading_level": 2,
      "content_instruction": "Decision approval metadata including who decided, when, context, and next review date",
      "min_paragraphs": 1,
      "max_paragraphs": 3,
      "error_message": "Approval section is mandatory to track decision authority and review schedule"
    },
    "Draft Notes": {
      "classification": "discouraged",
      "heading_level": 2,
      "warning_if_missing": "Draft notes should be removed before accepting the ADR"
    },
    "Open Questions": {
      "classification": "discouraged",
      "heading_level": 2,
      "warning_if_missing": "Open questions should be resolved before accepting the ADR"
    },
    "Internal Discussions": {
      "classification": "improper",
      "heading_level": 2,
      "error_message": "Internal discussions must not appear in published ADRs - move to team documentation"
    },
    "TODO": {
      "classification": "improper",
      "heading_level": 2,
      "error_message": "TODO sections are for development only - remove before publication"
    },
    "Temporary": {
      "classification": "improper",
      "heading_level": 2,
      "error_message": "Temporary markers must be removed before publication"
    }
  },
  "x-markitect-content-control": {
    "status": {
      "required_patterns": [
        "\\*\\*[A-Z][a-z]+\\*\\* - \\d{4}-\\d{2}-\\d{2}"
      ],
      "content_quality": {
        "min_words": 3,
        "max_words": 20
      },
      "content_instructions": [
        "Use format: **[Status]** - YYYY-MM-DD",
        "Valid statuses: Proposed, Accepted, Deprecated, Superseded",
        "Example: **Accepted** - 2025-11-10"
      ]
    },
    "context": {
      "discouraged_patterns": [
        "TODO",
        "FIXME",
        "\\bTBD\\b",
        "\\bXXX\\b"
      ],
      "content_quality": {
        "min_words": 100,
        "max_words": 2000,
        "readability_target": "technical",
        "min_sentences": 5
      },
      "content_instructions": [
        "Explain the background and circumstances",
        "Describe business or technical drivers",
        "Include Requirements subsection for specific needs",
        "Include Problem Statement subsection for clear problem articulation"
      ],
      "link_validation": {
        "check_internal": true,
        "check_external": false,
        "allow_fragments": true
      }
    },
    "decision": {
      "required_patterns": [
        "\\*\\*We will .+\\*\\*"
      ],
      "content_quality": {
        "min_words": 10,
        "max_words": 200
      },
      "content_instructions": [
        "Start with bold statement: **We will [decision]**",
        "Be specific and actionable",
        "Avoid ambiguity",
        "Example: **We will use IndexedDB for client-side debug log storage**"
      ]
    },
    "alternatives considered": {
      "content_quality": {
        "min_words": 150,
        "max_words": 3000,
        "readability_target": "technical"
      },
      "content_instructions": [
        "List all options evaluated (minimum 2)",
        "Include technology/implementation details for each",
        "Provide sufficient detail for future reviewers"
      ]
    },
    "decision matrix": {
      "required_patterns": [
        "\\|",
        "[-]+\\|",
        "[✅⚠️❌]"
      ],
      "content_instructions": [
        "Use markdown table format",
        "Include evaluation criteria as columns",
        "Use emoji indicators: ✅ (positive), ⚠️ (caution), ❌ (negative)",
        "Compare all alternatives systematically"
      ]
    },
    "rationale": {
      "required_patterns": [
        "### Why .+\\?",
        "### Why Not .+\\?"
      ],
      "content_quality": {
        "min_words": 100,
        "max_words": 2000,
        "readability_target": "technical"
      },
      "content_instructions": [
        "Include '### Why [Selected Option]?' subsection explaining the choice",
        "Include '### Why Not [Alternative]?' subsection(s) for each rejected option",
        "Provide technical and business justifications"
      ]
    },
    "implementation details": {
      "required_patterns": [
        "```"
      ],
      "content_quality": {
        "min_words": 50,
        "max_words": 3000,
        "readability_target": "technical"
      },
      "content_instructions": [
        "Include code examples with syntax highlighting",
        "Specify technical configurations",
        "Document integration points",
        "Provide sufficient detail for implementation"
      ]
    },
    "consequences": {
      "required_patterns": [
        "### Positive",
        "### Negative"
      ],
      "content_quality": {
        "min_words": 50,
        "max_words": 2000,
        "readability_target": "technical"
      },
      "content_instructions": [
        "Positive subsection: List benefits and advantages",
        "Negative subsection: List drawbacks and limitations",
        "Mitigation Strategies subsection: Address how negatives will be handled",
        "Be honest about trade-offs"
      ]
    },
    "approval": {
      "required_patterns": [
        "\\d{4}-\\d{2}-\\d{2}"
      ],
      "content_quality": {
        "min_words": 20,
        "max_words": 150
      },
      "content_instructions": [
        "Include: Decided by, Date, Context, Next Review",
        "Use ISO 8601 date format (YYYY-MM-DD)",
        "Specify review period for periodic reassessment"
      ]
    }
  },
  "type": "object",
  "properties": {
    "frontmatter": {
      "type": "object",
      "description": "Optional YAML frontmatter with ADR metadata",
      "properties": {
        "adr_number": {
          "type": "string",
          "pattern": "^[0-9]{3}$",
          "description": "Three-digit ADR number (e.g., '001', '042')"
        },
        "title": {
          "type": "string",
          "description": "Human-readable title of the decision"
        },
        "status": {
          "type": "string",
          "enum": ["Proposed", "Accepted", "Deprecated", "Superseded"],
          "description": "Current status of the ADR"
        },
        "date_decided": {
          "type": "string",
          "format": "date",
          "description": "Date when decision was made (YYYY-MM-DD)"
        },
        "date_next_review": {
          "type": "string",
          "format": "date",
          "description": "Date for next review (YYYY-MM-DD)"
        },
        "decided_by": {
          "type": "string",
          "description": "Person or team who made the decision"
        },
        "supersedes": {
          "type": "string",
          "description": "ADR number that this decision supersedes"
        },
        "superseded_by": {
          "type": "string",
          "description": "ADR number that supersedes this decision"
        }
      }
    },
    "headings": {
      "type": "object",
      "description": "Document heading structure",
      "properties": {
        "level_1": {
          "type": "array",
          "description": "Title heading in format: ADR-NNN: [Title]",
          "items": {
            "type": "object",
            "properties": {
              "content": {
                "type": "string",
                "pattern": "^ADR-[0-9]{3}: .+"
              }
            }
          },
          "minItems": 1,
          "maxItems": 1
        },
        "level_2": {
          "type": "array",
          "description": "Main section headings",
          "minItems": 6,
          "maxItems": 20
        },
        "level_3": {
          "type": "array",
          "description": "Subsection headings",
          "minItems": 3,
          "maxItems": 50
        }
      },
      "required": ["level_1", "level_2"]
    },
    "paragraphs": {
      "type": "array",
      "description": "Text paragraphs",
      "minItems": 15,
      "maxItems": 500
    },
    "code_blocks": {
      "type": "array",
      "description": "Code examples and technical specifications",
      "minItems": 0,
      "maxItems": 30
    },
    "lists": {
      "type": "array",
      "description": "Lists for alternatives, consequences, and structured information",
      "minItems": 3,
      "maxItems": 100
    },
    "tables": {
      "type": "array",
      "description": "Decision matrices and comparison tables",
      "minItems": 0,
      "maxItems": 10
    },
    "emphasis": {
      "type": "array",
      "description": "Bold and italic text for decisions and key terms",
      "minItems": 10,
      "maxItems": 200
    },
    "links": {
      "type": "array",
      "description": "References to external documentation and resources",
      "minItems": 0,
      "maxItems": 50
    }
  },
  "required": ["headings", "paragraphs", "lists", "emphasis"]
}

Version History

v1.0.0 (2026-01-06)

• Initial release of ADR schema
• 12 section classifications (7 required, 2 recommended, 2 optional, 2 discouraged, 3 improper)
• Comprehensive content control patterns for status, decision, rationale, and consequences
• Quality metrics for minimum word counts and readability
• Frontmatter support for ADR metadata tracking
• Filename convention validation

Related Documentation

• Schema Management Guide
• Schema Naming Specification
• Example ADR: ADR-001
• Example ADR: ADR-002
• MarkiTect Documentation