Version History

Versioning Policy

The Architecture Description Standard (ADS) uses semantic versioning:

MAJOR version - Structural changes that break backward compatibility (e.g., sections reorganised, removed, or fundamentally changed)
MINOR version - New sections, guidance additions, or non-breaking enhancements
PATCH version - Corrections, clarifications, typo fixes

The standard version (e.g. v1.3.0) and the JSON Schema version (e.g. v1.0.0) are versioned independently. The schema is the machine-readable contract that SADs and tooling validate against. The schema version only changes when the schema’s structure changes; minor and patch releases of the standard add content (guidance, examples, prompts) without touching the schema.

Versions and Schema Compatibility

Each release of the standard ties to a specific JSON Schema version. Major versions of the standard live at permanent versioned URLs so SADs and tooling targeting a previous version remain valid.

Standard Version	JSON Schema	URL	Status	Notes
v1.0.0	v1.0.0	archstandard.org/v1/	Superseded by v1.3.1	Initial release; schema established
v1.1.0	v1.0.0	archstandard.org/v1/	Superseded by v1.3.1	Content additions; schema unchanged
v1.2.0	v1.0.0	archstandard.org/v1/	Superseded by v1.3.1	Public release; schema unchanged
v1.3.0	v1.0.0	archstandard.org/v1/	Superseded by v1.3.1	Adoption release; schema unchanged
v1.3.1	v1.0.0	archstandard.org/v1/	Current	Bug fixes and SAD template polish; schema unchanged
v2.x (planned)	v2.0.0 (planned)	archstandard.org/v2/	In development	First schema major bump

Compatibility implication: any SAD that validates against schema v1.0.0 is structurally valid against any v1.x.y release of the standard. Editorial improvements (new prompts, new guidance, new examples) do not invalidate prior SADs. A schema v2.0.0 would only ship alongside a standard v2.0.0 major release; the current /v1/ URLs and the v1.0.0 schema would remain available permanently for backwards compatibility.

Third-party builders (see specification) should declare which schema version they target.

Releases

v1.0.0 - Initial Release

Date: 2026-03-27 · JSON Schema: v1.0.0

The first version of the Architecture Description Standard (ADS), synthesising years of practical experience in solution architecture with established frameworks:

ISO/IEC/IEEE 42010 - Architecture Description meta-model (stakeholders, concerns, viewpoints, views)
4+1 Architectural View Model - Six architectural views (extended from 5 with dedicated Data and Security views)
Cloud Well-Architected Frameworks - Quality attributes derived from AWS, Azure, GCP, Oracle, and IBM Well-Architected Frameworks
TOGAF - Architecture domain alignment (Business, Data, Application, Technology)
Industry SAD/HLD templates - Best practices from arc42, ServiceNow, NHS SAF, ALMBoK, and enterprise templates

Structure:

8 top-level sections (0-7)
6 Architectural Views
5 Quality Attributes
3 Documentation Depths (Minimum, Recommended, Comprehensive)
JSON Schema for multi-format generation
Framework alignment traceability

v1.1 - Examples and Guidance

Date: 2026-03-31 · JSON Schema: v1.0.0 (unchanged)

Four completed example SADs (Employee Directory, Customer API Platform, Cloud Migration, archstandard.org)
Scoring guidance (1/3/5) added to all section pages
Accessibility and neurodiversity improvements
French and German translations
Template generator script (schema as single source of truth)

v1.2.0 - Public Release

Date: 2026-04-13 · JSON Schema: v1.0.0 (unchanged)

Public launch of archstandard.org and GitHub repository
All example SADs available in JSON and Markdown download formats
Reading preferences toolbar (font choice, line spacing, focus mode, colour overlay)
Security hardening (CSP headers, Mermaid strict mode, dependency updates)
Depth Cheat Sheet for quick reference
Quickstart guide
Organisation customisation examples (YAML and JSON)
Full French and German translation parity (30 pages each)
Dual licence: CC BY 4.0 (content) + MIT (code)

v1.3.1 - Bug fixes and SAD template polish

Date: 2026-04-27 · JSON Schema: v1.0.0 (unchanged)

Patch release on top of v1.3.0. No content additions, no breaking changes — bug fixes and editorial polish from initial-review feedback.

Bug fixes:

Fixed broken Mermaid diagram in Medwick example (3.3.1 deployment diagram had a node ID containing spaces after the NHS→MediCore substitution)
Fixed schema canonical URL: now correctly serves at https://archstandard.org/schema/v1.0.0/ads.schema.json (matching the $id)
Fixed schema validation code samples (must download then validate locally; earlier examples used the unsupported -s URL form)
Sidebar scroll-spy: anchor sub-items in single-file standard sections (0, 1, 2, 5, 6, 7) now show active state when the matching section is in view
Consolidated validation instructions to a single canonical home on the JSON Schema page (was duplicated across 4 pages)

SAD template improvements:

Wide multi-column tables (e.g. Data Stores) now render as vertical Field/Value forms — readable in any output format
Word doc margins reduced to 15mm; lang: en-GB set so Word’s spell-checker uses UK English
“Author: Andi Chandler” removed from auto-generated headers (template is for the user to fill in)
Acronym dictionary expanded: SRE, DevOps, MLOps, DBA, CPU, RHEL, SUSE, CentOS, QA, CyberArk, CI/CD, Trade-off
“Quality Attribute Refs” → “Quality Attribute References” (full word)
Banner items now render as separate paragraphs in the Word doc

Editorial polish:

Stale NHS-flavoured Medwick descriptions updated across the site (now uses fictional “MediCore” framework consistently, including in the Medwick logo SVG)

v1.3.0 - Adoption Release

Date: 2026-04-24 · JSON Schema: v1.0.0 (unchanged)

Focus on making ADS easier to adopt, easier to review, and easier to teach.

New example SADs (four → seven):

NorthWind Retail — Recommended depth, Tier 2, PCI-DSS regulated e-commerce on AWS
Medwick Healthcare — Comprehensive depth, Tier 1, fictional national-healthcare patient portal with clinical safety standards, healthcare DSPT-equivalent governance, and FHIR R4 integration
Stellar Platform — Recommended depth, Tier 3, multi-cloud Internal Developer Platform on Kubernetes with Backstage

AI Prompt Library (new):

First-draft generator — produce a structured SAD from a brief
Validator — completeness, consistency, clarity, credibility
Scorer — apply the 0-5 compliance scale with justification
Improver — section-by-section suggestions for the next score level
Security review — CISO-office-style review
Governance review — ARB-style review

Guidance section (new):

What Good Looks Like — worked excerpts showing high-quality content
Anti-Patterns — common mistakes with before-and-after examples
Decision Guides — flowcharts for depth, threat model, split SADs, ADRs, RAID classification
Reviewer Perspectives — what ARB chair, Security, Data, SRE, Finance, Change, Product look for
Starter Kits — pre-scoped guidance for new cloud apps, migrations, integrations, platforms
Review Checklist — printable one-pager for governance reviewers
Industry Mappings — GDS Service Standard, NIST CSF, PCI-DSS, ISO 27001, NHS DSPT, UK GDPR, FCA
Cheat Cards — one-page printable references
The 2-Minute Pitch — speaker notes for introducing ADS internally

Contribution infrastructure:

CONTRIBUTING.md with style guide and contribution paths
CODE_OF_CONDUCT.md (principles-based)
GitHub issue templates for bug reports, feature requests, and example contributions

Other:

FAQ page answering common adoption questions
Examples index expanded to show all seven examples with downloadable Markdown and JSON

Roadmap

Future versions may include:

v2.0 — Community feedback incorporation and structural refinements. A v2.0 release would, for the first time, ship a new schema (v2.0.0) alongside it. The current schema (v1.0.0) and any SADs validated against it would remain available at /v1/ permanently.