From 4faadb7ecd7ab548319d0fb8b71ddd5459d72e30 Mon Sep 17 00:00:00 2001
From: tegwick <bernd.worsch@gmail.com>
Date: Wed, 19 Aug 2026 00:17:13 +0200
Subject: [PATCH] Register arc42-v1 schema for single-file architecture
 documents

Twelve required chapters, checklist recommended. First-wave estate
documents validate against it.
---
 markitect/schemas/arc42-schema-v1.0.md | 115 +++++++++++++++++++++++++
 markitect/schemas/schema-catalog.yaml  |  22 ++++-
 2 files changed, 133 insertions(+), 4 deletions(-)
 create mode 100644 markitect/schemas/arc42-schema-v1.0.md

diff --git a/markitect/schemas/arc42-schema-v1.0.md b/markitect/schemas/arc42-schema-v1.0.md
new file mode 100644
index 00000000..6eb7d78a
--- /dev/null
+++ b/markitect/schemas/arc42-schema-v1.0.md
@@ -0,0 +1,115 @@
+---
+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
+    }
+  }
+}
+```
diff --git a/markitect/schemas/schema-catalog.yaml b/markitect/schemas/schema-catalog.yaml
index e729ec74..767b62ed 100644
--- a/markitect/schemas/schema-catalog.yaml
+++ b/markitect/schemas/schema-catalog.yaml
@@ -48,6 +48,24 @@ schemas:
     created: "2026-01-04"
     updated: "2026-01-04"
 
+  - id: "arc42-v1"
+    name: "arc42 Architecture Documentation Schema"
+    file: "arc42-schema-v1.0.md"
+    version: "1.0"
+    description: "Schema for a single-file arc42 architecture document (chapters 1–12 required)"
+    type: "document-schema"
+    usage: "Validates first-wave and complete arc42 system documents"
+    document_types:
+      - architecture
+      - arc42
+    tags:
+      - documentation
+      - architecture
+      - arc42
+    author: "MarkiTect Project"
+    created: "2026-08-19"
+    updated: "2026-08-19"
+
 # Future schemas to add:
 #
 # - id: "manpage-v1"
@@ -58,10 +76,6 @@ schemas:
 #   name: "API Reference Schema"
 #   description: "Schema for API endpoint documentation"
 #
-# - id: "arc42-v1"
-#   name: "arc42 Architecture Documentation Schema"
-#   description: "Schema for arc42 architecture documentation template"
-#
 # - id: "adr-v1"
 #   name: "Architecture Decision Record Schema"
 #   description: "Schema for ADR (Architecture Decision Record) documents"