Specification Description Standard (Draft)
Spec Schema
A unified specification standard for the repository: human-readable, machine-validatable, and independent of any specific tool.
- A verifiable specification standard, not just a collection of Markdown files.
- Supports complex repository structures, not only flat lists of documents.
- Does not impose a workflow and is not tied to any specific AI agent and SDD tool.
Spec Driven Development is an approach in which development relies on the specification as the primary source of truth. Our standard makes such specifications formal and verifiable: it describes how Markdown files and their structure in the repository should be organized so they stay convenient for people and reliable for automated processing.
Example spec
spec.schema.yaml
version: 0.0.7
entity:
domain:
idPrefix: DOM
pathTemplate: "spec/domains/${slug}/index.md"
content:
sections:
goal:
title: Goal
service:
idPrefix: SVC
pathTemplate: "${refs.domain.dirPath}/services/${slug}/index.md"
meta:
fields:
domain:
schema:
type: entityRef
refType: domain
tier:
schema:
type: string
enum: [gold, silver, bronze]
feature:
idPrefix: FEAT
pathTemplate:
cases:
- when: ${refs.service}
use: "${refs.service.dirPath}/features/${meta.status}/${slug}.md"
- use: "spec/features/${meta.status}/${slug}.md"
meta:
fields:
service:
required: false
schema:
type: entityRef
refType: service
owner:
schema:
type: string
status:
schema:
type: string
enum: [draft, testing, actual, deprecated]
priority:
schema:
type: string
enum: [p0, p1, p2]
linked_epic:
required: false
schema:
type: entityRef
refType: feature
test_file:
required: ${meta.status == 'testing' || meta.status == 'actual'}
schema:
type: string
content:
sections:
goal:
title: Goal
scope:
title: Scope
acceptance:
title: Acceptance Criteria
rollout:
required: ${meta.service}
title: Rollout
adr:
idPrefix: ADR
pathTemplate: "${refs.context.dirPath}/adr/${createdDate}-${slug}.md"
meta:
fields:
context:
schema:
type: entityRef
refType: [domain, service, feature]
decision_status:
schema:
type: string
enum: [proposed, accepted, rejected, superseded]
impact:
schema:
type: string
enum: [low, medium, high]
supersedes:
schema:
type: entityRef
refType: adr
content:
sections:
context:
title: Context
decision:
title: Decision
alternatives:
title: Alternatives
integration-impact:
required: ${refs.context.type == 'service'}
title: Integration Impact
consequences:
title: Consequences
Possible file structure
No separate file structure index is needed. This is just an example layout defined and validated by
spec.schema.yaml.
spec/
├── domains/
│ ├── commerce/
│ │ ├── index.md
│ │ ├── adr/
│ │ │ ├── 2026-01-12-commerce-boundaries.md
│ │ │ └── 2026-01-28-build-vs-buy-payments.md
│ │ └── services/
│ │ ├── checkout-api/
│ │ │ ├── index.md
│ │ │ ├── adr/
│ │ │ │ └── 2026-02-02-checkout-session-strategy.md
│ │ │ └── features/
│ │ │ ├── draft/
│ │ │ │ └── guest-checkout-v2.md
│ │ │ ├── testing/
│ │ │ │ └── one-click-checkout.md
│ │ │ ├── actual/
│ │ │ │ ├── smart-cart-recovery.md
│ │ │ │ └── adr/
│ │ │ │ └── 2026-02-01-smart-cart-recovery-tradeoffs.md
│ │ │ └── deprecated/
│ │ │ └── legacy-checkout-flow.md
│ │ └── pricing-engine/
│ │ ├── index.md
│ │ ├── adr/
│ │ │ └── 2026-01-25-dynamic-pricing-safety-rails.md
│ │ └── features/
│ │ ├── draft/
│ │ │ └── b2b-contract-pricing.md
│ │ ├── testing/
│ │ │ └── promo-stack-limiter.md
│ │ └── actual/
│ │ └── margin-protection-rules.md
│ └── growth/
│ ├── index.md
│ ├── adr/
│ │ └── 2026-01-19-growth-experimentation-model.md
│ └── services/
│ ├── identity-gateway/
│ │ ├── index.md
│ │ ├── adr/
│ │ │ └── 2026-01-18-session-token-rotation.md
│ │ └── features/
│ │ ├── draft/
│ │ │ └── passwordless-login.md
│ │ └── actual/
│ │ ├── risk-based-authentication.md
│ │ └── adr/
│ │ └── 2026-01-23-risk-score-threshold-policy.md
│ └── notification-hub/
│ ├── index.md
│ ├── adr/
│ │ └── 2026-01-21-multi-channel-delivery-policy.md
│ └── features/
│ ├── testing/
│ │ └── send-time-optimization.md
│ └── actual/
│ └── transactional-notification-sla.md
└── features/
├── draft/
│ └── partner-marketplace-launch.md
├── testing/
│ └── referral-program-v2.md
├── actual/
│ ├── loyalty-tier-program.md
│ └── adr/
│ └── 2026-01-27-loyalty-points-expiration-policy.md
└── deprecated/
└── manual-campaign-workflow.md