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

Every v1.x release of the standard targets JSON Schema v1.0.0 and is published at archstandard.org/v1/. Major versions live at permanent versioned URLs so SADs and tooling targeting a previous version remain valid. A future v2.0.0 of the standard would ship a v2.0.0 schema at /v2/, with /v1/ and the v1.0.0 schema preserved indefinitely.

Version	Status	Notes
v1.3.2	Current	Schema consistency fixes and section 6.6/6.8/6.10 additions
v1.3.1	Superseded	Bug fixes and SAD template polish
v1.3.0	Superseded	Adoption release
v1.2.0	Superseded	Public release
v1.1.0	Superseded	Content additions
v1.0.0	Superseded	Initial release; schema established
v2.x	Planned	First schema major bump (v2.0.0)

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.

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

Releases

Releases are listed newest-first.

v1.3.2 - Schema consistency and Section 6 additions

Date: 2026-04-28 · JSON Schema: v1.0.0 (additions only — backwards compatible)

Patch release closing internal-consistency gaps between the schema, the standard text, and the worked examples. All seven examples now validate clean against the schema.

Schema additions (additive — old SADs remain valid):

• riskGovernance.technicalDebt — array of TD-NNN entries (id, description, category, impact, remediation plan, target date, owner) for Section 6.6 Technical Debt Register
• riskGovernance.architectureDecisionsLog — governance summary index for Section 6.8 Architectural Decisions Log, referencing full ADRs in architecturalViews.scenarios.adrs (Section 3.6.2) by id
• approvals[].conditions — optional string capturing conditions on a sign-off

Schema corrections:

• New canonical $defs/classification (public, internal, restricted, highly-restricted) replaces three inline duplicate enums; removes the stray “confidential” value that had drifted into Document Control
• Added paas-app-service to physicalView compute types (Cloud Migration example was using it)
• External integrations protocol enum brought to parity with internal protocol: added jdbc, odbc, mqtts, websocket, wss, ldaps, ssh; added kerberos to authentication methods (Customer API Platform example was using jdbc)

Structural fix:

• approvals relocated from appendices.approvals to riskGovernance.approvals. Per the standard, Section 6.10 Approval Sign-Off is the closing governance act of Section 6, not an appendix. Examples migrated; templates and the rendered SAD now correctly place 6.10 under Section 6.

Section-tag corrections:

• Compliance Traceability is now correctly tagged 6.9 (was 6.8)
• Guardrail-exception fields (policyExceptions, policyExceptionsAccepted, processExceptions, riskProfileImpact) tagged 6.7
• Glossary tagged 7.1, References tagged 7.2

Template / SAD-builder polish:

• Section headings in the generated sad-template.{md,yaml,docx} now show numbered prefixes for 6.6, 6.7, 6.8, 6.9, 6.10, 7.1, 7.2 — matching the standard

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

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.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.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

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.