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.3/.
intent.deliveryForm (9-value enum) — closes the §10 orphaned-guidance gap: the delivery-form axis §10.2–10.8 lean on is now declarable by producers.intent.architecturalStyle (enum) and intent.architecturalPatterns[] (open string + registry/patterns.json).envelope.persistence (replication / consistency / backup / encryption) and concurrency detail on envelope.instantiation (ordering / idempotency / conflictResolution).envelope.dependencies[].type split into deliveryForm + role, so one delivery-form vocabulary serves both subject and dependency.registry/patterns.json added; registry/delivery-forms.json extended to 9 forms (adds desktop_app, mobile_app, browser_extension).v0.1 and v0.2 frozen at their URIs 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 SAM’s own CC-BY-4.0 wording, anchored to the ISO names and framed through SAM’s declaration model, with example producer claims. Informative, not a reproduction or replacement of the ISO text.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 named a vocabulary producers and consumers commonly use that SAM had no slot for. All landed in v0.3; the descriptions below record the design.
architecturalStyle (declarative)Shipped as a single-value hard enum on intent:
monolith | modular_monolith | microservices | serverless | event_driven | actor | hybrid
Producers scope their claims; consumers match the style against their target architecture. Distinct from subject.layer (granularity of this manifest) and from subject.components[] (composition). Design-context, not a graded claim (§5.5).
intent.architecturalPatterns[] + registry/patterns.jsonShipped as an open string array on intent — a flat list of pattern IDs the software implements:
"architecturalPatterns": ["circuit_breaker", "cqrs", "cache_aside"]
Companion registry/patterns.json (same shape as tensions.json) seeds 15 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). Advisory (open string, not a hard enum — like tensionsDeclared.tension); an unregistered, non-x:-prefixed ID is schema-valid-but-spec-nonconforming. Each registry entry’s applies_to maps the pattern to the qualityAttributes sub-characteristic it serves — the pattern’s evidentiary weight lives there, not on the pattern (§5.5).
Closes the gap that producers couldn’t name “this implements circuit-breaker” or “this is event-sourced” — vocabulary every senior engineer expects.
Extended envelope.persistence (was just required + stores[]) with four hard enums: replication (single / primary_replica / multi_primary / sharded), consistency (strong / read_after_write / eventual), backup (none / snapshot / continuous), encryption (none / at_rest / in_flight / both).
Extended envelope.instantiation (was just mode + coordinationDependency) with three hard enums: ordering (none / per_key / total), idempotency (none / keyed / global), conflictResolution (last_write_wins / crdt / application_defined / none).
Expand §10 from definitions into a per-characteristic SAM lens — for each characteristic, ~3 lines of SAM-specific authoring guidance ISO structurally cannot have: how you declare it (typical status values, what a verified claim requires here, which industryRefs[] anchor it, whether the concept also lives in envelope/extensions) and what an honest claim looks like (when not_applicable is the truthful call). Evens out the thin entries (e.g. compatibility.coExistence, several performanceEfficiency subs) that still read close to a restatement, seeds the deferred Authoring Guide inline, and makes §10 decisively non-derivative of ISO. (Substantially done — §10.2–10.8 now carry the SAM lens, grounded on the delivery-form taxonomy below; §10.1 (correctness fleshed) and §10.9 (safety, already domain-specific) were adequately concrete.)
intent.deliveryForm — shipped in v0.3Closed the §10 orphaned-guidance gap: §10.2–10.8 depend on this axis, and it is now a declarable field.
A hard enum for how the software is delivered and who operates it — saas / self_hosted_service / library / cli_tool / desktop_app / mobile_app / browser_extension / infrastructure / appliance (9 forms; the client-side family cli_tool/desktop_app/mobile_app/browser_extension was completed during implementation), documented in registry/delivery-forms.json. The same quality key asserts a measured SLO for producer-operated software and a default-plus-sizing-guidance for consumer-operated software; the field lets consumers filter and tooling apply the right reading automatically. Source model (proprietary / open_source / source_available) remains an orthogonal candidate field, not part of this enum (deferred to v0.4).
The envelope.dependencies[].type split shipped alongside it: type (a single enum that mixed delivery form with functional role) was replaced by deliveryForm (the shared vocabulary above) + role (identity_provider, payment_provider, data_provider, communication_provider, observability_provider, ml_model_provider, other) — the one breaking change in v0.3 (§6.6). One delivery-form vocabulary now serves both subject and dependency.
Chosen as a hard enum (consistent with intent.audience and the former dependencies[].type), so an unknown value is invalid rather than advisory. Conformance: pass-with-deliveryform, fail-14-bad-deliveryform, pass-with-dependency-role, fail-17-dependency-legacy-type.
architecturalStyle / architecturalPatterns — resolved in v0.3 (§5.5)Surfaced by the v0.3 review: unlike qualityAttributes (which carry status / evidence[]), these two fields were bare self-assertions an AI agent might over-trust. Resolved in v0.3 via a spec patch (§5.5), deliberately not an evidence ladder — architecture resists direct evidence (no artifact proves “this is microservices” the way a load test proves a latency claim), so a status / evidence shape would manufacture assurance that does not exist. §5.5 scopes intent.architecturalStyle / architecturalPatterns[] as declarative design-context (not graded), states that a pattern’s verifiable effect lives in the qualityAttributes sub-characteristic it serves (registry applies_to gives the mapping), and notes they are layer-sensitive (declare where true; a product composes from components[]). deliveryForm was already exempt (verifiable-by-consequence).
serverless_function delivery formThe review flagged FaaS (Lambda-style code the consumer deploys but a cloud operator runs) as not mapping cleanly onto saas or self_hosted_service. Partly covered today by intent.architecturalStyle: serverless, so it is a defensible omission — revisit if authoring feedback shows the delivery/operation split matters for FaaS.
intent.sourceModelDeferred from v0.3: the orthogonal proprietary / open_source / source_available axis that governs the maintainability reading (§10.7). Candidate as a separate optional enum on intent.
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[].registry/delivery-forms.json — advisory registry (9 forms); its vocabulary is the intent.deliveryForm / envelope.dependencies[].deliveryForm enum as of v0.3.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/below), still open, 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 (SAM’s own definitions, anchored to the ISO names and framed through SAM’s declaration model) plus §1.5 open companions. §10 is informative; the ISO standard remains authoritative for the model.Resolved in v0.3:
intent.architecturalStyle (hard enum).intent.architecturalPatterns[] (open string) + registry/patterns.json (15 IDs).envelope.persistence.{replication, consistency, backup, encryption}.envelope.instantiation.{ordering, idempotency, conflictResolution}.intent.deliveryForm (9-form hard enum) and the dependencies[].type → deliveryForm + role split (§6.6); closed the §10 orphaned-guidance gap.§5.5 scopes the architecture fields as declarative design-context, not graded claims (deliberately not an evidence ladder — architecture resists direct evidence).Open / no decision yet:
SPECIFICATION.md §10.8 gives authoring guidance — prefer declared over not_applicable unless there are genuinely no consumers to disrupt. Still open for v0.4: whether to turn that guidance into a schema-enforced constraint (gathering 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.