This roadmap is feedback-driven, not predetermined. Everything below shifts in response to issues filed, real-world authoring experience, and review from supply-chain / security / procurement practitioners. Items are ordered by current confidence, not by guaranteed delivery.
The stable target is v1. The path there is incremental minor releases that close gaps surfaced by real use.
Live at https://software-architecture-spec.github.io/sam/v0.2/.
envelope.serviceLevels, intent.tenancy.dataResidency[], and industryRefs[] audit metadata (auditor / auditPeriod / dateAttested)v0.1 frozen at /sam/v0.1/ and remains valid per §6.3 same-MAJOR compatibility.
These were the v0.2 candidates carried forward from the v0.1 review and now in the schema:
SPECIFICATION.md §10) — all 9 ISO 25010 characteristics and 40 sub-characteristics defined in our own CC-BY-4.0 wording with example producer claims. Closes the paywalled-ISO gap.envelope.serviceLevels (service/product-layer only; if/then enforces) — availability, rpoMinutes / rtoMinutes, supportWindow, incidentResponse keyed by severity, vulnerabilityPatch keyed by severity, industryRefs[].intent.tenancy.dataResidency[] — string array; ISO 3166 codes, regional groupings, cloud regions, or producer-defined options.industryRefs[] audit-metadata enrichment — optional auditor, auditPeriod, dateAttested on every industryRefs entry (qualityAttributes claims, dependencies, serviceLevels).§1.5) — Wikipedia ISO 25010, arc42 quality model, NIST SP 800-160 Vol. 1 as informational broadening for readers who want context beyond the §10 definitions.Drawn from a review of canonical systems-design literature (Release It! / DDIA / Fowler PEAA / SRE Book / Newman / Richards & Ford / Ousterhout) — each names a vocabulary producers and consumers commonly use that SAM has no slot for today.
architecturalStyle (declarative)Single-value enum on intent declaring the architectural style:
monolith | modular_monolith | microservices | serverless | event_driven | actor | hybrid
Producers can scope their claims; consumers can match the style against their target architecture. Distinct from subject.layer (granularity of this manifest) and from subject.components[] (composition).
architecturalPatterns[] + registry/patterns.jsonA new array on qualityAttributes.*.overall (or top-level architecturalPatterns[] — to be decided) for declaring named patterns the software implements:
[
{ "id": "circuit_breaker", "appliesTo": ["dependencies", "reliability"] },
{ "id": "cqrs", "appliesTo": ["data"] },
{ "id": "cache_aside", "appliesTo": ["performance"] }
]
Companion registry/patterns.json (same shape as tensions.json) seeds canonical IDs from Release It! (circuit_breaker, bulkhead, timeout, fail_fast, retry_with_backoff, fallback), DDIA (event_sourcing, cqrs, saga, outbox), Fowler PEAA (unit_of_work, repository), and caching literature (cache_aside, write_through, write_back).
Closes the gap that producers can’t declare “this implements the circuit-breaker pattern” or “this is event-sourced” — vocabulary every senior engineer expects to see.
envelope.persistence today is a stores[] enum (sql, kv, document, blob, search, queue, filesystem, other). v0.3 candidates: replication topology (single / primary-replica / multi-primary / sharded), consistency model (strong / read-after-write / eventual), backup posture (none / snapshot / continuous), encryption posture (at-rest / in-flight / both).
envelope.instantiation.mode today covers singleton / multi_instance / leader_elected / sharded. v0.3 candidates: ordering guarantees (none / per-key / total), idempotency claims, conflict-resolution model (last-write-wins / CRDT / application-defined).
Carried forward unchanged into v0.3+:
subject.digest; binding without a content-addressed digest is currently underspecified.These are prose-heavy and depend on observed authoring patterns. They’ll land once we have enough real manifests to learn from.
evidence required when status: verified), §5.1.7 (summary required when status: declared|verified), §5.1.9 (interpretable industryRefs.standard), §5.1.11 (well-known or x:-prefixed tensionsDeclared.tension). The conformance corpus already exercises these; what’s missing is the validator that consumes the corpus.standards.json — community contributions adding aliases and new entries as real SAMs cite standards we haven’t seen yet.registry/patterns.json — seeded in v0.3 alongside architecturalPatterns[].software-architecture-spec.github.io namespace is a working-draft host. The intended long-term home is a neutral standards body (CNCF, OpenSSF, IETF SIG, or similar). Adoption depends on real-world traction, which depends on this release generating engagement.x-sam-stability validation behavior. Currently descriptive only (per §8.3). Future versions may give it semantics — e.g., consumers reject manifests that promise stable but use fields marked experimental.v1.0. Declared when the v0.x field set has stabilized through real use, conformance test surface is comprehensive, the canonical-strings registry has settled, and at least one working-group home has accepted the spec.These came out of consumer-side review and design-pattern coverage analysis. Each is either resolved (above), v0.3 candidate (above), or out-of-scope (below) — listed here so the reasoning is visible.
Resolved in v0.2:
intent.tenancy.dataResidency[].industryRefs[] — landed as optional auditor / auditPeriod / dateAttested fields.envelope.serviceLevels (service/product layer only).SPECIFICATION.md §10 definitions appendix and §1.5 open companions. SAM is now usable from §10 alone without paywalled ISO access.Open / v0.3 candidates:
intent.architecturalStyle enum.architecturalPatterns[] + registry/patterns.json.envelope.persistence is thin; reviewers want replication topology, consistency model, backup posture. Proposed: expand envelope.persistence for v0.3.envelope.instantiation.mode is thin; reviewers want ordering guarantees, idempotency, conflict resolution. Proposed: expand envelope.instantiation for v0.3.Open / no decision yet:
flexibility.replaceability: not_applicable as “philosophically odd — every system has a replaceability story.” Possible v0.3 wording change in SPECIFICATION.md §10.8 to constrain when not_applicable is appropriate; gathering more authoring feedback first.artifact / service / product hierarchy without the spec. The model itself is sound; the README and authoring guide can do better at signaling the hierarchy at a glance.Explicitly out of scope (carried forward):
alternative enum field is coarser than DORA expects. The alternative field signals architectural substitutability; cutover plans are contractual.SAM is an architectural visibility framework, not a compliance framework. The line below isn’t a refusal of compliance use cases — it’s a refusal of letting compliance use cases dictate the shape of the architectural surface. Consumers under any specific regime read SAM to populate their own compliance artifacts; SAM’s job is the architectural input layer that survives every regime simultaneously.
These are real concerns adjacent to SAM but not SAM’s job:
industryRefs[] and evidence URIs.subject.sbomRef.File an issue. The real-world-feedback template surfaces what’s blocking actual use; the schema-change-proposal template proposes specific shape. Roadmap reordering happens in response to that input, not in advance of it.