META.scm

Table of Contents

• The .scm Format Family
• What is META.scm?
• Why META.scm?
• Core Sections
  • Architecture Decisions (architecture-decisions)
  • Development Practices (development-practices)
  • Design Rationale (design-rationale)
• Getting Started
  • Create a META.scm File
  • Validate with JSON Schema
• Specification
  • Format Family
  • META.scm Specific
• Examples
• Integration with STATE.scm
• Standards Track
• Media Type
• ADR Status Values
• Tooling (Planned)
• Contributing
• License
• Related Work

Machine-readable Engineering and Technical Architecture files.

Part of the .scm Format Family — Scheme S-expression data formats for software engineering workflows.

The .scm Format Family

Format	Purpose	Use Case
META.scm	Project governance and architecture documentation	ADRs, development practices, design rationale
STATE.scm	AI conversation checkpoint and restore	Session persistence, context continuity

Both formats share common S-expression syntax, enabling unified tooling while serving complementary purposes.

What is META.scm?

META.scm is a format specification for documenting software project metadata, architecture decisions, and development practices in machine-readable Scheme S-expression syntax.

;; SPDX-License-Identifier: MIT
(define-module (my-project meta)
  #:export (architecture-decisions development-practices design-rationale))

(define architecture-decisions
  '((adr-001
     (title . "Use Event Sourcing")
     (status . "accepted")
     (date . "2025-01-15")
     (context . "Need complete audit trail for orders")
     (decision . "Implement event sourcing for order service")
     (consequences . ("Full history" "Replay capability" "Eventual consistency")))))

(define development-practices
  '((testing (framework . "pytest") (coverage-minimum . 80))
    (versioning (scheme . "Semantic Versioning 2.0.0"))))

(define design-rationale
  '((why-event-sourcing
     "Event sourcing provides immutable audit trail and temporal queries.")))

Why META.scm?

Feature	Benefit
Machine-Readable	Tooling can parse, validate, and generate documentation
Human-Readable	S-expressions are readable without special editors
Structured ADRs	Architecture decisions in queryable format
VCS-Friendly	Plain text diffs, merges, and history
Extensible	Add custom sections without breaking compatibility
Cross-Format	STATE.scm can reference META.scm for project context

Core Sections

Architecture Decisions (architecture-decisions)

Structured Architecture Decision Records (ADRs):

• Unique identifier (adr-NNN)

• Title, status, date

• Context (problem statement)

• Decision (what was decided)

• Consequences (implications)

Development Practices (development-practices)

Codified development standards:

• code-style - Formatters, linters, type systems

• security - Security requirements

• testing - Test frameworks, coverage requirements

• versioning - Version scheme, changelog format

• deployment - Deployment strategy, environments

• review - Code review process

Design Rationale (design-rationale)

Narrative explanations of key decisions, linking to ADRs.

Getting Started

Create a META.scm File

;; SPDX-License-Identifier: MIT
;; SPDX-FileCopyrightText: 2025 Your Name

;;; META.scm — Architecture Decisions and Development Practices
;;; your-project

(define-module (your-project meta)
  #:export (architecture-decisions
            development-practices
            design-rationale))

(define architecture-decisions
  '((adr-001
     (title . "Your First Decision")
     (status . "accepted")
     (date . "2025-01-01")
     (context . "Describe the problem or situation")
     (decision . "What you decided")
     (consequences . ("Consequence 1" "Consequence 2")))))

(define development-practices
  '((code-style
     (formatter . "your-formatter")
     (linter . "your-linter"))))

(define design-rationale
  '((why-this-decision
     "Explain the reasoning behind your key decisions.")))

Validate with JSON Schema

For environments with JSON Schema support, convert to JSON and validate against spec/schema/meta.schema.json.

Specification

The formal specification is in the spec/ directory:

Format Family

• SCM-FORMAT-FAMILY.adoc - .scm format family overview

• UNIFIED-STANDARDS-STRATEGY.adoc - Coordinated standards approach

• shared/s-expression.abnf - Shared ABNF grammar

• shared/scm-common.schema.json - Shared JSON Schema

META.scm Specific

• META-FORMAT-SPEC.adoc - Complete specification

• abnf/meta.abnf - ABNF grammar

• schema/meta.schema.json - JSON Schema

• VERSION-POLICY.adoc - Version policy

• STANDARDS-TRACK.adoc - Standardization roadmap

• IANA-MEDIA-TYPE.adoc - Media type registration

Examples

See the examples/ directory:

• minimal.scm - Minimal valid META file

• comprehensive.scm - Full-featured example

Integration with STATE.scm

STATE.scm files (AI session checkpoints) can reference META.scm for project context:

;; In STATE.scm
(define projects
  '((name . "my-project")
    (path . "/home/user/my-project")
    (meta-ref . "META.scm")           ; Reference to project's META.scm
    (active-adrs . (adr-001 adr-003)) ; Currently relevant decisions
    (relevant-practices . (security testing))))

This enables AI assistants to:

• Query architecture decisions during implementation

• Enforce development practices

• Understand design rationale

• Maintain context across sessions

Standards Track

The .scm Format Family is on track for formal standardization:

Phase	Target	Status
Community Specification	Reference implementations, community adoption	In Progress
IANA Registration	application/meta+scheme media type	Planned
IETF RFC Series	Core syntax + format-specific RFCs	Planned

See UNIFIED-STANDARDS-STRATEGY.adoc for the coordinated roadmap.

Media Type

• MIME Type: application/meta+scheme

• File Extension: .scm (conventionally META.scm)

• Encoding: UTF-8

ADR Status Values

Status	Meaning
proposed	Under consideration
accepted	Decided and in effect
deprecated	No longer recommended
superseded	Replaced by another decision
rejected	Considered but not adopted

Tooling (Planned)

• VS Code extension with syntax highlighting and validation

• CLI tool for linting and documentation generation

• CI/CD integration for ADR policy enforcement

• Markdown/HTML documentation generator

• Shared S-expression parser library (TypeScript, Rust, Python)

Contributing

See CONTRIBUTING.md for contribution guidelines.

License

MIT License. Copyright (c) 2025 Jonathan D.A. Jewell.

Related Work

• MADR - Markdown ADR format

• SPDX - Software Package Data Exchange

• ISO/IEC 5962:2021 - SPDX as ISO standard

• STATE.scm - AI conversation checkpoint format (companion specification)