JSON Schema

This page is for developers, tooling builders, and AI practitioners who want to validate, generate, analyse, or process SADs programmatically. If you are writing a SAD manually, you can skip this page and use the templates instead.

Overview

The ADS defines a formal JSON Schema (v1.0.0) that enables both authoring and analysis of architecture documents:

Writing:

• AI-assisted authoring — import the schema into an LLM to generate structured first drafts from a project brief
• Generation — generate blank templates in multiple formats (JSON, YAML, Markdown, Word)
• Validation — validate completed SADs against the standard structure

Reading and analysis:

• Programmatic parsing — read and extract data from SADs using standard JSON/YAML tooling
• Portfolio analysis — compare SADs across projects to identify coverage gaps, common risks, or technology patterns
• Compliance reporting — audit SADs at scale against the scoring criteria
• AI-assisted review — import a completed SAD into an LLM for quality assessment or gap analysis

Extending:

• Extensibility — add organisation-specific sections via customSections and organisationProfile

Schema Location

The schema file is located at /schema/ads.schema.json in the repository.

Schema ID: https://archstandard.org/schema/v1.0.0/ads.schema.json

Schema Structure

The schema maps directly to the standard’s sections:

ads.schema.json
├── schemaVersion          "1.0.0"
├── documentControl        Section 0: metadata, history, contributors
├── executiveSummary       Section 1: overview, context, scope, decisions
├── stakeholders           Section 2: register, concerns, compliance
├── architecturalViews     Section 3
│   ├── logicalView        3.1: components, services, patterns
│   ├── integrationView     3.2: connectivity, integrations, APIs
│   ├── physicalView       3.3: hosting, compute, networking, environments
│   ├── dataView           3.4: data stores, classification, privacy
│   ├── securityView       3.5: IAM, encryption, monitoring
│   └── scenarios          3.6: use cases, ADRs
├── qualityAttributes      Section 4: quality attributes + tradeoffs
├── lifecycleManagement    Section 5: SDLC, operations, exit planning
├── riskGovernance         Section 6: constraints, risks, decisions, compliance
├── appendices             Section 7: glossary, references, approvals
├── organisationProfile    Organisation-specific configuration
└── customSections[]       Extension point for additional sections

Key Schema Features

Documentation Depths

Sections use a maturityLevel enum with three values. Note: the schema uses the property name maturityLevel while the standard’s prose refers to this concept as “Documentation Depth” — they mean the same thing:

{ "type": "string", "enum": ["minimum", "recommended", "comprehensive"] }

Quality Attribute References

Any section can reference applicable quality attributes:

{
  "qualityAttributeRefs": ["reliability", "performance", "cost-optimisation"]
}

Organisation Profile

The organisationProfile extension allows mapping the generic standard to organisation-specific tools and governance:

{
  "organisationProfile": {
    "organisationName": "Acme Corp",
    "tooling": {
      "cmdb": "ServiceNow",
      "secretStore": "HashiCorp Vault",
      "monitoring": "Datadog"
    },
    "governanceGates": [
      {
        "gateName": "Dev/Test Review",
        "requiredMaturityLevel": "minimum",
        "requiredSections": ["documentControl", "executiveSummary", "architecturalViews.logicalView"]
      },
      {
        "gateName": "Production Approval",
        "requiredMaturityLevel": "recommended"
      }
    ]
  }
}

Custom Sections

Add organisation-specific sections without modifying the core schema:

{
  "customSections": [
    {
      "id": "cloud-governance",
      "title": "Cloud Governance",
      "description": "Organisation-specific cloud governance requirements",
      "content": "...",
      "maturityLevel": "recommended",
      "parentSection": "physicalView"
    }
  ]
}

Required vs Optional Fields

The schema enforces only the Minimum documentation depth as required:

Required Field	Section
schemaVersion	Root
documentControl.metadata	0. Document Control
executiveSummary.solutionOverview	1. Executive Summary
architecturalViews	3. Architectural Views
riskGovernance.risks	6. Decision Making & Governance

All other fields are optional, allowing progressive adoption from Minimum through Comprehensive documentation depths.

Validation Example

Validate a SAD against the schema using local or remote references:

# Using ajv-cli (local schema)
npx ajv validate -s schema/ads.schema.json -d my-sad.json

# Using ajv-cli (remote schema)
npx ajv validate -s https://archstandard.org/schema/v1.0.0/ads.schema.json -d my-sad.json

# Using Python jsonschema
pip install jsonschema
python -m jsonschema -i my-sad.json schema/ads.schema.json

The schema is hosted at: https://archstandard.org/schema/v1.0.0/ads.schema.json

Building Tools with the Schema

The JSON Schema is designed to be consumed by tooling — form builders, validators, converters, and SAD management platforms. Custom extension properties make this easier:

Extension	Purpose	Example
x-ads-section	Section number	"3.1", "6.3"
x-ads-title	Display name	"Logical View", "Risks"
x-ads-depth	Documentation depth	"minimum", "recommended", "comprehensive"

These extensions are present on every major section and sub-section in the schema. A tool can walk the schema tree and use these properties to:

• Generate forms with correct section grouping, labels, and depth indicators
• Show/hide sections based on the user’s chosen documentation depth
• Validate completeness against a specific documentation depth
• Export to JSON, YAML, Markdown, or DOCX

// Example: fetch the schema and list all sections
const schema = await fetch('https://archstandard.org/schema/v1.0.0/ads.schema.json').then(r => r.json());

for (const [key, def] of Object.entries(schema.$defs)) {
  if (def['x-ads-section']) {
    console.log(`${def['x-ads-section']} ${def['x-ads-title']} [${def['x-ads-depth']}]`);
  }
}