From a0cf18aa1987b0bc7de4f0653799ed6e0ba7bebc Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 15 Dec 2025 19:46:55 +0000 Subject: [PATCH] feat: Integrate STATE.scm and ECOSYSTEM.scm into SCM Format Family Unify both formats under a shared standards infrastructure: New family infrastructure (spec/family/): - SCM-FAMILY.adoc: Complete family specification with diagrams - scm-core.abnf: Shared ABNF primitives for all family formats - scm-family.schema.json: Unified JSON Schema for both formats Updated ECOSYSTEM.scm: - Added `family` form declaring SCM family membership - Enhanced STATE.scm relationship with integration patterns - Added cross-reference documentation - New `standards-track` form for coordination status Updated STANDARDS-ROADMAP.adoc: - Renamed to "SCM Format Family Standards Roadmap" - Added Phase 1.5 for family integration (complete) - Coordinated IETF submission strategy - Batch IANA registration plan - Unified implementation approach The two formats now share: - Common S-expression primitives - Unified media type pattern (application/vnd.*+scm) - Cross-referencing capability - Coordinated standardisation timeline --- ECOSYSTEM.scm | 149 +++++++-- README.adoc | 144 +++++++-- STANDARDS-ROADMAP.adoc | 503 +++++++++++++++++------------ spec/family/SCM-FAMILY.adoc | 423 ++++++++++++++++++++++++ spec/family/scm-core.abnf | 262 +++++++++++++++ spec/family/scm-family.schema.json | 308 ++++++++++++++++++ 6 files changed, 1541 insertions(+), 248 deletions(-) create mode 100644 spec/family/SCM-FAMILY.adoc create mode 100644 spec/family/scm-core.abnf create mode 100644 spec/family/scm-family.schema.json diff --git a/ECOSYSTEM.scm b/ECOSYSTEM.scm index 1bba083..b147e1d 100644 --- a/ECOSYSTEM.scm +++ b/ECOSYSTEM.scm @@ -3,6 +3,7 @@ ;; ECOSYSTEM.scm - Ecosystem Description Format Specification ;; Version: 1.0.0-draft ;; Canonical Reference Implementation +;; Family: SCM Format Family (ecosystem (version "1.0.0-draft") @@ -10,30 +11,89 @@ (type "specification") (purpose "Declarative format for describing software project ecosystems and inter-project relationships") + ;; ========================================================================= + ;; SCM FORMAT FAMILY MEMBERSHIP + ;; ========================================================================= + + (family + (name "SCM Format Family") + (role "family-member") + (family-spec "spec/family/SCM-FAMILY.adoc") + (shared-grammar "spec/family/scm-core.abnf") + (siblings + (sibling + (name "STATE.scm") + (domain "session-state") + (media-type "application/vnd.state+scm")) + (sibling + (name "ECOSYSTEM.scm") + (domain "project-context") + (media-type "application/vnd.ecosystem+scm")))) + + ;; ========================================================================= + ;; ECOSYSTEM POSITION + ;; ========================================================================= + (position-in-ecosystem - "This is the SPECIFICATION layer - defines the format itself. - Tool implementations consume this format to understand project relationships. - Enables automated dependency mapping, documentation generation, and ecosystem visualization.") + "Part of the SCM Format Family - a collection of declarative S-expression + formats for capturing software development context. + + ECOSYSTEM.scm defines the PROJECT CONTEXT layer: + - What a project IS and IS NOT + - Where it fits in the broader ecosystem + - Relationships to other projects + - Integration boundaries and intentions + + Complements STATE.scm which handles SESSION STATE: + - Conversation context and preferences + - Project progress and velocity + - Decision queues and action items + + Together they provide complete context for AI-assisted development.") + + ;; ========================================================================= + ;; RELATED PROJECTS + ;; ========================================================================= (related-projects + ;; Primary sibling (project (name "STATE.scm") (url "https://github.com/hyperpolymath/state.scm") (relationship "sibling-standard") (description "Stateful Context Tracking Engine for AI Conversation Continuity") (differentiation - "STATE.scm = Conversation/session persistence format - ECOSYSTEM.scm = Project relationship and context format")) + "STATE.scm captures TEMPORAL context: + - Session state, conversation history + - Project progress tracking + - Decision queues, velocity metrics + + ECOSYSTEM.scm captures STRUCTURAL context: + - Project identity and boundaries + - Inter-project relationships + - Ecosystem position and integration") + (integration-notes + "Use both together for complete context: + - ECOSYSTEM.scm in repository root (static, versioned with code) + - STATE.scm for session persistence (dynamic, conversation-specific) + Cross-reference pattern: + (state + (metadata + (ecosystem-ref \"./ECOSYSTEM.scm\")))")) + + ;; Potential consumers (project (name "echomesh") (url "https://github.com/hyperpolymath/echomesh") (relationship "potential-consumer") (description "Conversation context preservation across sessions") (integration-notes - "Could use ECOSYSTEM.scm to declare project relationships - and STATE.scm for conversation persistence")) + "Could use SCM family formats: + - ECOSYSTEM.scm for project topology + - STATE.scm for session handoff")) + ;; Inspirations (project (name "Schema.org") (url "https://schema.org") @@ -41,28 +101,57 @@ (description "Structured data vocabulary for the web") (differentiation "Schema.org = Web-focused, JSON-LD/microdata - ECOSYSTEM.scm = Developer-focused, S-expression native"))) + SCM Family = Developer-focused, S-expression native")) + + (project + (name "SPDX") + (url "https://spdx.dev") + (relationship "inspiration") + (description "Software Package Data Exchange - license and component metadata") + (differentiation + "SPDX = Supply chain, licensing, SBOM + ECOSYSTEM.scm = Project relationships, boundaries"))) + + ;; ========================================================================= + ;; WHAT THIS IS / IS NOT + ;; ========================================================================= (what-this-is "A declarative S-expression format for describing: - - Project identity (name, type, purpose) - - Ecosystem position and relationships + + IDENTITY + - Project name, type, and purpose + - Version and authorship + + RELATIONSHIPS - Related projects with typed relationships - - Explicit boundaries (what-this-is / what-this-is-not) - - Integration intentions and differentiation + - Consumer/producer/sibling/alternative/etc. + - Differentiation statements - Design principles: + BOUNDARIES + - What this project IS (capabilities, scope) + - What this project IS NOT (explicit non-goals) + - Integration intentions + + DESIGN PRINCIPLES - Human-readable and version-control friendly - Self-documenting through explicit relationship types - Minimal required fields, rich optional metadata - - S-expression syntax for tooling compatibility") + - S-expression syntax for tooling compatibility + - Part of unified SCM Format Family") (what-this-is-not "- NOT a package manifest (see Cargo.toml, package.json) - NOT a build configuration (see justfile, Makefile) - NOT dependency lock file (see Cargo.lock, package-lock.json) - NOT API documentation (see rustdoc, typedoc) - - NOT runtime configuration (see .env, config.toml)") + - NOT runtime configuration (see .env, config.toml) + - NOT session state (see STATE.scm for that) + - NOT CI/CD configuration (see .github/workflows)") + + ;; ========================================================================= + ;; SPECIFICATION METADATA + ;; ========================================================================= (specification (format "S-expression (symbolic expression)") @@ -70,11 +159,31 @@ (file-extension ".scm") (media-type "application/vnd.ecosystem+scm") (grammar-definition "spec/ecosystem.abnf") - (json-schema "spec/ecosystem.schema.json")) + (shared-grammar "spec/family/scm-core.abnf") + (json-schema "spec/ecosystem.schema.json") + (internet-draft "spec/draft/draft-jewell-ecosystem-scm-00.txt") + (family-spec "spec/family/SCM-FAMILY.adoc")) + + ;; ========================================================================= + ;; STANDARDS & FUTURE + ;; ========================================================================= + + (standards-track + (body "IETF") + (type "Informational RFC") + (status "draft") + (coordination "Unified with STATE.scm as SCM Format Family") + (roadmap "STANDARDS-ROADMAP.adoc")) (future-integration - "Standards track progression: + "Standards track progression (coordinated with STATE.scm): 1. Community review and iteration (current) - 2. IETF Internet-Draft submission - 3. IANA media type registration - 4. Tooling ecosystem development")) + 2. Reference implementations (Rust, TypeScript) + 3. IETF Internet-Draft submission (coordinated family) + 4. IANA media type registration (family batch) + 5. Tooling ecosystem development + + Potential future family members: + - BUILD.scm (declarative build configuration) + - CONFIG.scm (application configuration) + - DEPLOY.scm (deployment context)")) diff --git a/README.adoc b/README.adoc index 2dea669..d22919d 100644 --- a/README.adoc +++ b/README.adoc @@ -9,7 +9,7 @@ == Overview -**ECOSYSTEM.scm** is a declarative S-expression format for describing software project ecosystems and inter-project relationships. +**ECOSYSTEM.scm** is a declarative S-expression format for describing software project ecosystems and inter-project relationships. It is part of the **SCM Format Family**. [source,scheme] ---- @@ -38,6 +38,58 @@ - NOT an inference engine (bring your own)")) ---- +== SCM Format Family + +ECOSYSTEM.scm is part of a family of declarative S-expression formats: + +[source] +---- +┌─────────────────────────────────────────────────────────────────┐ +│ SCM Format Family │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌─────────────────┐ ┌─────────────────┐ │ +│ │ STATE.scm │◄────────►│ ECOSYSTEM.scm │ │ +│ │ │ cross- │ │ │ +│ │ Session State │ ref │ Project Context │ │ +│ │ Progress Track │ │ Relationships │ │ +│ │ Decision Queue │ │ Boundaries │ │ +│ └────────┬────────┘ └────────┬────────┘ │ +│ │ │ │ +│ └────────────┬───────────────┘ │ +│ │ │ +│ ┌───────────┴───────────┐ │ +│ │ Shared Foundation │ │ +│ │ scm-core.abnf │ │ +│ │ Unified media types │ │ +│ └───────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +---- + +[cols="2,3,3"] +|=== +| Aspect | STATE.scm | ECOSYSTEM.scm + +| *Domain* +| Temporal context (sessions) +| Structural context (projects) + +| *Captures* +| Conversation state, progress, decisions +| Relationships, boundaries, integration + +| *Persistence* +| Dynamic, per-session +| Static, versioned with code + +| *Media Type* +| `application/vnd.state+scm` +| `application/vnd.ecosystem+scm` +|=== + +See link:spec/family/SCM-FAMILY.adoc[SCM-FAMILY.adoc] for the complete family specification. + == Why ECOSYSTEM.scm? Modern software exists within ecosystems of interrelated projects. Yet no standard format exists to formally declare: @@ -56,6 +108,7 @@ ECOSYSTEM.scm fills this gap with a human-readable, version-control friendly, ma * **Project disambiguation** - Clarify boundaries between similar projects * **Integration planning** - Assess compatibility before adoption * **Onboarding** - Help new contributors understand project context +* **AI context** - Provide project context to AI assistants (pairs with STATE.scm) == Quick Start @@ -99,14 +152,29 @@ Place in your repository root: "We focus on X; they focus on Y"))) ---- -=== 3. Validate (Optional) +=== 3. Integrate with STATE.scm (Optional) + +Reference your ECOSYSTEM.scm from STATE.scm for complete context: + +[source,scheme] +---- +;; In your STATE.scm file +(state + (metadata + (version "2.0") + (ecosystem-ref "./ECOSYSTEM.scm")) ; Cross-reference + (user ...) + (session ...)) +---- + +=== 4. Validate (Optional) -Convert to JSON and validate against the schema: +Validate against the unified family schema: [source,bash] ---- # Using a hypothetical scm-to-json tool -scm-to-json ECOSYSTEM.scm | jsonschema -i - spec/ecosystem.schema.json +scm-to-json ECOSYSTEM.scm | jsonschema -i - spec/family/scm-family.schema.json ---- == Specification @@ -117,6 +185,7 @@ scm-to-json ECOSYSTEM.scm | jsonschema -i - spec/ecosystem.schema.json * **Encoding:** UTF-8 * **Media Type:** `application/vnd.ecosystem+scm` * **File Extension:** `.ecosystem.scm` or `ECOSYSTEM.scm` +* **Shared Grammar:** `spec/family/scm-core.abnf` === Required Fields @@ -143,6 +212,9 @@ scm-to-json ECOSYSTEM.scm | jsonschema -i - spec/ecosystem.schema.json |=== | Field | Description +| `family` +| SCM family membership declaration + | `position-in-ecosystem` | Where this project fits in the broader ecosystem @@ -155,11 +227,14 @@ scm-to-json ECOSYSTEM.scm | jsonschema -i - spec/ecosystem.schema.json | `what-this-is-not` | Explicit boundaries and non-goals -| `future-integration` -| Planned integrations and roadmap - | `specification` | Technical metadata (for spec documents) + +| `standards-track` +| Standardisation status and roadmap + +| `future-integration` +| Planned integrations |=== === Relationship Types @@ -178,7 +253,7 @@ scm-to-json ECOSYSTEM.scm | jsonschema -i - spec/ecosystem.schema.json | Same organisation or ecosystem | `sibling-standard` -| Related specification +| Related specification (e.g., STATE.scm) | `complementary` | Works alongside this project @@ -201,7 +276,7 @@ scm-to-json ECOSYSTEM.scm | jsonschema -i - spec/ecosystem.schema.json == Standards Track -ECOSYSTEM.scm is pursuing formal standardisation through the **IETF Informational RFC** track. +ECOSYSTEM.scm is pursuing formal standardisation through the **IETF Informational RFC** track as part of a coordinated SCM family submission. === Current Status @@ -217,14 +292,26 @@ ECOSYSTEM.scm is pursuing formal standardisation through the **IETF Informationa | `spec/ecosystem.abnf` | ✓ Complete +| Shared ABNF core +| `spec/family/scm-core.abnf` +| ✓ Complete + | JSON Schema | `spec/ecosystem.schema.json` | ✓ Complete +| Unified family schema +| `spec/family/scm-family.schema.json` +| ✓ Complete + | Internet-Draft | `spec/draft/draft-jewell-ecosystem-scm-00.txt` | ✓ Complete +| SCM Family spec +| `spec/family/SCM-FAMILY.adoc` +| ✓ Complete + | IANA considerations | `spec/IANA-CONSIDERATIONS.adoc` | ✓ Complete @@ -239,6 +326,7 @@ ECOSYSTEM.scm is pursuing formal standardisation through the **IETF Informationa * Strong precedent for data formats (GeoJSON RFC 7946, iCalendar RFC 5545) * Accessible, well-understood process * Free and volunteer-driven +* Coordinated family submission for STATE.scm and ECOSYSTEM.scm * Leads to IANA media type registration See link:STANDARDS-ROADMAP.adoc[STANDARDS-ROADMAP.adoc] for the complete standardisation plan. @@ -250,13 +338,17 @@ See link:STANDARDS-ROADMAP.adoc[STANDARDS-ROADMAP.adoc] for the complete standar ECOSYSTEM.scm/ ├── ECOSYSTEM.scm # Canonical specification (self-describing) ├── README.adoc # This file -├── STANDARDS-ROADMAP.adoc # Standardisation plan +├── STANDARDS-ROADMAP.adoc # Unified family standardisation plan ├── spec/ -│ ├── ecosystem.abnf # Formal ABNF grammar (RFC 5234) -│ ├── ecosystem.schema.json # JSON Schema for validation +│ ├── ecosystem.abnf # Format-specific ABNF grammar +│ ├── ecosystem.schema.json # Format-specific JSON Schema │ ├── IANA-CONSIDERATIONS.adoc -│ └── draft/ -│ └── draft-jewell-ecosystem-scm-00.txt # IETF I-D +│ ├── draft/ +│ │ └── draft-jewell-ecosystem-scm-00.txt +│ └── family/ # Shared SCM family infrastructure +│ ├── SCM-FAMILY.adoc # Family specification +│ ├── scm-core.abnf # Shared ABNF primitives +│ └── scm-family.schema.json # Unified validation schema ├── CONTRIBUTING.md ├── CODE_OF_CONDUCT.md ├── SECURITY.md @@ -265,13 +357,19 @@ ECOSYSTEM.scm/ == Related Projects -=== STATE.scm +=== STATE.scm (Sibling Standard) -Sibling format for AI conversation state persistence. +Session state persistence for AI conversation continuity. * Repository: https://github.com/hyperpolymath/state.scm * Relationship: `sibling-standard` -* Differentiation: STATE.scm handles session state; ECOSYSTEM.scm handles project context +* Domain: Temporal context (sessions, progress, decisions) +* Integration: Cross-reference via `ecosystem-ref` in STATE.scm metadata + +**Use together for complete context:** + +* ECOSYSTEM.scm in repository root (static, versioned with code) +* STATE.scm for session persistence (dynamic, conversation-specific) == Contributing @@ -279,10 +377,11 @@ See link:CONTRIBUTING.md[CONTRIBUTING.md] for guidelines. === Priority Contributions -1. **Reference implementations** - Parsers in Rust, TypeScript, Python -2. **Tooling** - Validators, linters, converters -3. **Editor support** - Syntax highlighting, snippets -4. **Feedback** - Use the format and report issues +1. **Unified parser library** - Rust library handling both STATE.scm and ECOSYSTEM.scm +2. **TypeScript implementation** - For VS Code extension and web tooling +3. **Validation tools** - CLI validators using family schema +4. **Editor support** - Syntax highlighting, snippets, LSP +5. **Feedback** - Use the formats and report issues == Licence @@ -290,5 +389,6 @@ MIT License - see link:LICENSE[LICENSE] == Contact -* Issues: https://github.com/hyperpolymath/ECOSYSTEM.scm/issues +* ECOSYSTEM.scm Issues: https://github.com/hyperpolymath/ECOSYSTEM.scm/issues +* STATE.scm Issues: https://github.com/hyperpolymath/state.scm/issues * Discussions: https://github.com/hyperpolymath/ECOSYSTEM.scm/discussions diff --git a/STANDARDS-ROADMAP.adoc b/STANDARDS-ROADMAP.adoc index da7cd3d..920bdd9 100644 --- a/STANDARDS-ROADMAP.adoc +++ b/STANDARDS-ROADMAP.adoc @@ -1,4 +1,4 @@ -= ECOSYSTEM.scm Standards Track Roadmap += SCM Format Family Standards Roadmap :author: Jonathan D.A. Jewell :revdate: 2025-12-15 :toc: @@ -8,175 +8,210 @@ == Executive Summary -ECOSYSTEM.scm is a declarative S-expression format for describing software project ecosystems and inter-project relationships. This document outlines the path to formal standardisation. +The **SCM Format Family** is a collection of declarative S-expression formats for software development context. This document outlines the unified standardisation strategy for the family. -**Recommended Standards Track:** IETF Informational RFC +**Current Members:** -**Rationale:** Data interchange formats have strong precedent at IETF (RFC 7946 GeoJSON, RFC 5545 iCalendar, RFC 8259 JSON). The IETF process is well-understood, accessible, and appropriate for developer tooling formats. +* **STATE.scm** - Session state persistence for AI conversations +* **ECOSYSTEM.scm** - Project ecosystem context and relationships -== Standards Bodies Evaluation - -=== IETF (Recommended) - -[cols="1,4"] -|=== -| Aspect | Assessment +**Recommended Standards Track:** IETF Informational RFC (coordinated family submission) -| *Fit* -| ✓ Excellent. Data format specifications are core IETF territory. +**Rationale:** Data interchange formats have strong precedent at IETF (RFC 7946 GeoJSON, RFC 5545 iCalendar). Submitting as a coordinated family ensures consistent design and simplifies IANA registration. -| *Precedent* -| RFC 7946 (GeoJSON), RFC 5545 (iCalendar), RFC 8259 (JSON), RFC 7763 (Markdown) +== SCM Format Family Overview -| *Process* -| Internet-Draft → IETF Last Call → RFC publication - -| *Timeline* -| 6-18 months for Informational RFC +[source] +---- +┌─────────────────────────────────────────────────────────────────────┐ +│ SCM Format Family │ +├─────────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌──────────────────┐ ┌──────────────────┐ │ +│ │ STATE.scm │ │ ECOSYSTEM.scm │ │ +│ │ │ │ │ │ +│ │ Session State │◄────────►│ Project Context │ │ +│ │ Progress Track │ cross- │ Relationships │ │ +│ │ Decision Queue │ ref │ Boundaries │ │ +│ └────────┬─────────┘ └────────┬─────────┘ │ +│ │ │ │ +│ └─────────────┬───────────────┘ │ +│ │ │ +│ ┌───────────┴───────────┐ │ +│ │ Shared Foundation │ │ +│ │ - scm-core.abnf │ │ +│ │ - scm-family.schema │ │ +│ │ - Common media type │ │ +│ │ pattern │ │ +│ └───────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────────┘ +---- -| *Cost* -| Free (volunteer-driven) +=== Domain Separation -| *Requirements* -| Rough consensus, running code, community review +[cols="2,3,3"] |=== +| Aspect | STATE.scm | ECOSYSTEM.scm -*Track Options:* +| *Domain* +| Temporal context +| Structural context -1. **Informational RFC** (Recommended initially) - - Documents existing practice - - No mandatory implementation requirements - - Appropriate for new formats seeking adoption +| *Scope* +| Single session/conversation +| Project lifetime -2. **Standards Track RFC** (Future) - - Requires demonstrated interoperability - - Multiple independent implementations - - Appropriate after adoption grows +| *Persistence* +| Dynamic, conversation-specific +| Static, versioned with code -=== IRTF (Not Recommended) +| *Location* +| Working directory, temp +| Repository root -[cols="1,4"] +| *Media Type* +| `application/vnd.state+scm` +| `application/vnd.ecosystem+scm` |=== -| Aspect | Assessment -| *Fit* -| ✗ Poor. IRTF is for research, not operational specifications. +=== Integration Pattern -| *Purpose* -| Long-term research groups, experimental protocols +[source,scheme] +---- +;; STATE.scm references ECOSYSTEM.scm +(state + (metadata + (version "2.0") + (ecosystem-ref "./ECOSYSTEM.scm")) ; Cross-reference + (user ...) + (session ...) + (projects ...)) + +;; ECOSYSTEM.scm declares STATE.scm as sibling +(ecosystem + (family + (siblings + (sibling (name "STATE.scm") (domain "session-state")))) + (related-projects + (project + (name "STATE.scm") + (relationship "sibling-standard")))) +---- -| *Verdict* -| ECOSYSTEM.scm is practical tooling, not research. -|=== +== Standards Bodies Evaluation -=== ISO (Not Recommended) +=== IETF (Recommended) [cols="1,4"] |=== | Aspect | Assessment | *Fit* -| ✗ Poor. ISO focuses on industrial/manufacturing standards. +| ✓ Excellent. Data format specifications are core IETF territory. -| *Timeline* -| 3-5 years minimum +| *Precedent* +| RFC 7946 (GeoJSON), RFC 5545 (iCalendar), RFC 8259 (JSON) -| *Cost* -| Significant (national body fees, committee participation) +| *Family Support* +| Related RFCs common (e.g., RFC 7231 HTTP methods family) | *Process* -| Requires national body sponsorship +| Internet-Draft → IETF Last Call → RFC publication + +| *Timeline* +| 6-18 months for Informational RFC -| *Verdict* -| Overkill for software developer tooling formats. +| *Cost* +| Free (volunteer-driven) |=== -=== W3C (Not Recommended) +=== Alternative Bodies -[cols="1,4"] +[cols="2,2,3"] |=== -| Aspect | Assessment +| Body | Fit | Notes -| *Fit* -| ○ Partial. W3C focuses on web standards. +| IRTF +| ✗ Poor +| Research-focused, not operational specs -| *Scope* -| Browser technologies, semantic web, accessibility +| ISO +| ✗ Poor +| Industrial focus, 3-5 year timeline, high cost -| *Process* -| Working Group → Candidate Recommendation → Recommendation +| W3C +| ○ Partial +| Web-focused; SCM is developer tooling -| *Verdict* -| ECOSYSTEM.scm is not web-specific; IETF is better fit. -|=== +| ECMA +| ○ Partial +| Language-focused; accessible alternative -=== ECMA (Not Recommended) - -[cols="1,4"] +| OASIS +| ○ Acceptable +| Fallback if IETF stalls |=== -| Aspect | Assessment -| *Fit* -| ○ Partial. ECMA standardises programming languages. +== Unified Roadmap -| *Precedent* -| ECMAScript, JSON (ECMA-404), C# +=== Phase 1: Foundation ✓ COMPLETE -| *Process* -| Technical Committee sponsorship required +**Status:** Complete for both formats -| *Verdict* -| JSON went ECMA path, but IETF is more accessible. +[cols="3,1,1,3"] |=== +| Deliverable | STATE | ECO | Location -=== OASIS (Alternative) +| Canonical specification +| ✓ +| ✓ +| `STATE.scm`, `ECOSYSTEM.scm` -[cols="1,4"] -|=== -| Aspect | Assessment +| Format-specific ABNF +| ✓ +| ✓ +| `spec/*.abnf` -| *Fit* -| ○ Acceptable. OASIS handles structured information standards. - -| *Precedent* -| AMQP, MQTT, DocBook, OpenDocument +| JSON Schema +| ✓ +| ✓ +| `spec/*.schema.json` -| *Process* -| Technical Committee → Committee Specification → Standard +| Internet-Draft +| ✓ +| ✓ +| `spec/draft/draft-jewell-*-00.txt` -| *Verdict* -| Viable alternative if IETF process stalls. +| IANA considerations +| ✓ +| ✓ +| `spec/IANA-CONSIDERATIONS.adoc` |=== -== Roadmap Phases +=== Phase 1.5: Family Integration ✓ COMPLETE -=== Phase 1: Foundation (Current) - -**Status:** ✓ Complete +**Status:** Complete [cols="3,1,3"] |=== | Deliverable | Status | Location -| Canonical specification file +| SCM Family specification | ✓ Done -| `ECOSYSTEM.scm` +| `spec/family/SCM-FAMILY.adoc` -| ABNF grammar (RFC 5234) +| Shared ABNF core | ✓ Done -| `spec/ecosystem.abnf` +| `spec/family/scm-core.abnf` -| JSON Schema +| Unified JSON Schema | ✓ Done -| `spec/ecosystem.schema.json` +| `spec/family/scm-family.schema.json` -| Internet-Draft +| Cross-references updated | ✓ Done -| `spec/draft/draft-jewell-ecosystem-scm-00.txt` - -| IANA considerations -| ✓ Done -| `spec/IANA-CONSIDERATIONS.adoc` +| Both `*.scm` files |=== === Phase 2: Community Review @@ -185,17 +220,17 @@ ECOSYSTEM.scm is a declarative S-expression format for describing software proje **Objectives:** -* [ ] Publish draft specification for community feedback +* [ ] Publish both specs for community feedback * [ ] Gather implementation experience -* [ ] Refine grammar based on real-world usage -* [ ] Build reference parser/validator +* [ ] Refine shared grammar based on usage +* [ ] Validate cross-format integration patterns **Actions:** -1. Announce on relevant forums/mailing lists -2. Create GitHub Discussions for feedback -3. Track issues and incorporate improvements -4. Document implementation notes +1. Announce SCM family on relevant forums +2. Create unified GitHub Discussions +3. Track issues across both repositories +4. Document integration patterns === Phase 3: Implementation @@ -203,122 +238,173 @@ ECOSYSTEM.scm is a declarative S-expression format for describing software proje **Objectives:** -* [ ] Reference implementation (Rust recommended) -* [ ] Parser libraries for major languages +* [ ] Unified parser library (handles both formats) * [ ] Validation tools +* [ ] Format conversion utilities * [ ] Editor/IDE support -**Minimum Implementations for Standards Track:** +**Shared Implementation Strategy:** -[cols="2,2,2"] +[source,rust] +---- +// Hypothetical unified parser API +use scm_family::{parse, Document, Format}; + +let doc = parse(content)?; + +match doc.format() { + Format::State(state) => { + // Access STATE.scm specific fields + let user = state.user()?; + let projects = state.projects()?; + } + Format::Ecosystem(eco) => { + // Access ECOSYSTEM.scm specific fields + let related = eco.related_projects()?; + let position = eco.position_in_ecosystem()?; + } +} +---- + +**Implementation Priority:** + +[cols="2,2,3"] |=== | Language | Priority | Notes | Rust -| High -| Reference implementation +| Primary +| Unified reference implementation + +| TypeScript +| Primary +| VS Code extension, web tooling -| TypeScript/JavaScript +| Guile Scheme | High -| Web tooling, Node.js +| Native format, REPL integration | Python | Medium -| Broad ecosystem +| Scripting, data analysis | Go | Medium -| Cloud tooling - -| Scheme/Racket -| Medium -| Native S-expression support +| Cloud tooling, CI/CD |=== -=== Phase 4: IETF Submission +=== Phase 4: Coordinated IETF Submission **Timeline:** Month 6-9 +**Strategy:** Submit both I-Ds simultaneously with cross-references + **Actions:** 1. Create IETF Datatracker account -2. Submit Internet-Draft via https://datatracker.ietf.org/submit/ -3. Request review from ART (Applications and Real-Time) Area -4. Respond to reviewer feedback -5. Iterate on draft versions (-01, -02, etc.) +2. Submit both Internet-Drafts: + - `draft-jewell-state-scm-00` + - `draft-jewell-ecosystem-scm-00` +3. Reference shared family in both I-Ds +4. Request ART Area review (coordinated) +5. Iterate on both drafts together -**Draft Naming Convention:** +**Draft Structure:** -* Individual submission: `draft-jewell-ecosystem-scm-XX` -* If adopted by WG: `draft-ietf--ecosystem-scm-XX` +[source] +---- +draft-jewell-state-scm-00 +├── References draft-jewell-ecosystem-scm-00 +└── References shared ABNF core + +draft-jewell-ecosystem-scm-00 +├── References draft-jewell-state-scm-00 +└── References shared ABNF core +---- === Phase 5: IANA Registration **Timeline:** Upon I-D acceptance -**Actions:** +**Batch Registration:** + +[cols="2,3,2"] +|=== +| Media Type | Specification | Status + +| `application/vnd.state+scm` +| draft-jewell-state-scm +| Pending -1. Expert review of media type registration -2. Submit registration via https://www.iana.org/form/media-types -3. Await IANA processing -4. Verify registration in media types registry +| `application/vnd.ecosystem+scm` +| draft-jewell-ecosystem-scm +| Pending + +| `application/vnd.scm` (reserved) +| Future family container +| Reserved +|=== === Phase 6: RFC Publication **Timeline:** Month 12-18 +**Target:** Two related Informational RFCs published together + **Milestones:** -1. IETF Last Call (2 weeks) -2. IESG Review +1. Coordinated IETF Last Call +2. IESG Review (both documents) 3. RFC Editor processing -4. Publication as RFC XXXX +4. Simultaneous publication == Success Criteria -=== For Informational RFC +=== For Family Informational RFCs -* [ ] Clear, complete specification -* [ ] At least one working implementation +* [ ] Clear, complete specifications for both formats +* [ ] Shared ABNF core documented and validated +* [ ] At least one unified implementation +* [ ] Cross-format integration demonstrated * [ ] No technical objections during Last Call -* [ ] IANA registration approved +* [ ] Both IANA registrations approved === For Future Standards Track -* [ ] Two or more independent implementations +* [ ] Two or more independent implementations per format * [ ] Demonstrated interoperability -* [ ] Adoption in production systems -* [ ] No IPR (intellectual property) encumbrances +* [ ] Production adoption of integration patterns +* [ ] No IPR encumbrances == Governance Model -=== During Development (Current) +=== Family Stewardship -* **Maintainer:** Jonathan D.A. Jewell -* **Contributions:** Via GitHub Pull Requests -* **Decisions:** Maintainer discretion with community input +* **Family Steward:** Jonathan D.A. Jewell +* **Individual Format Maintainers:** May be delegated +* **Shared Infrastructure:** Coordinated changes required -=== Post-RFC Publication +=== Versioning Strategy -* **Change Control:** IETF (for RFC-track changes) -* **Community Input:** Via errata, new I-Ds -* **Versioning:** Semantic versioning for format; RFC numbers for spec - -== Related Standards Coordination +[cols="2,3"] +|=== +| Component | Strategy -=== STATE.scm +| Individual formats +| Semantic versioning (independent) -Sibling format for AI conversation state persistence. +| Shared ABNF core +| Semantic versioning (triggers format review) -* Coordinate media type family -* Share parser infrastructure -* Align versioning strategy +| Family specification +| Document version (coordination updates) +|=== -=== Potential Liaisons +=== Change Process -* **schema.org:** Structured data alignment -* **SPDX:** License expression compatibility -* **OpenAPI:** API ecosystem description +1. **Format-specific changes:** Normal PR to respective repo +2. **Shared grammar changes:** PR to both repos with coordination +3. **Family-level changes:** Discussion in designated forum == Risk Assessment @@ -326,37 +412,58 @@ Sibling format for AI conversation state persistence. |=== | Risk | Likelihood | Mitigation -| Lack of adoption +| Formats diverge | Medium -| Build tooling, demonstrate value +| Shared grammar, coordinated releases -| IETF process delays +| Adoption imbalance | Medium -| Operate as de facto standard initially +| Promote together, unified tooling -| Competing formats +| IETF coordination overhead | Low -| Differentiate clearly, focus on niche +| Same author, related content + +| Conflicting evolution +| Low +| Family steward oversight | IPR claims | Very Low | MIT licence, contributor agreement - -| Format design flaws -| Low -| Community review, iterate before standardising |=== == Timeline Summary [source] ---- -2025 Q4: Phase 1 Complete (Foundation) ✓ CURRENT +2025 Q4: Phase 1 Complete (Individual foundations) ✓ +2025 Q4: Phase 1.5 Complete (Family integration) ✓ CURRENT 2026 Q1: Phase 2 (Community Review) -2026 Q2: Phase 3 (Implementation) -2026 Q2: Phase 4 (IETF Submission) -2026 Q3: Phase 5 (IANA Registration) -2026 Q4: Phase 6 (RFC Publication Target) +2026 Q2: Phase 3 (Unified Implementation) +2026 Q2: Phase 4 (Coordinated IETF Submission) +2026 Q3: Phase 5 (Batch IANA Registration) +2026 Q4: Phase 6 (Simultaneous RFC Publication) +---- + +== Repository Structure + +[source] +---- +ECOSYSTEM.scm/ state.scm/ +├── ECOSYSTEM.scm ├── STATE.scm +├── STANDARDS-ROADMAP.adoc (this file) ├── (may reference this) +├── spec/ ├── spec/ +│ ├── ecosystem.abnf │ ├── state.abnf +│ ├── ecosystem.schema.json │ ├── state.schema.json +│ ├── IANA-CONSIDERATIONS.adoc │ ├── IANA-CONSIDERATIONS.adoc +│ ├── draft/ │ ├── draft/ +│ │ └── draft-jewell-ecosystem-* │ │ └── draft-jewell-state-* +│ └── family/ ←──────────────────────┼───┤ +│ ├── SCM-FAMILY.adoc │ │ (shared or mirrored) +│ ├── scm-core.abnf │ │ +│ └── scm-family.schema.json │ │ +└── README.adoc └── README.adoc ---- == Appendix: IETF Process Reference @@ -368,31 +475,15 @@ Sibling format for AI conversation state persistence. * https://authors.ietf.org/[I-D Author Resources] * https://datatracker.ietf.org/submit/[I-D Submission Tool] -=== Document Status Progression - -[source] ----- -Individual I-D → WG Adoption (optional) → IETF Last Call → IESG Review → RFC ----- - -=== Informational RFC Requirements - -1. Does not establish Internet standards -2. Documents information of general interest -3. Requires rough consensus -4. No mandatory implementation - -== Appendix: Alternative Paths - -If IETF is not pursued, alternatives in order of preference: +=== Related RFC Precedents -1. **De facto standard** - Publish, build tooling, let adoption drive recognition -2. **OASIS** - Submit as Technical Committee proposal -3. **Community Group** - Form working group (e.g., under Rust Foundation, CNCF) +* **RFC 7946 + RFC 7464:** GeoJSON and JSON Text Sequences +* **RFC 5545 + RFC 6321:** iCalendar and xCal (XML) +* **HTTP RFCs:** Multiple related documents == Contact -For questions about standardisation: +For questions about SCM family standardisation: -* GitHub: https://github.com/hyperpolymath/ECOSYSTEM.scm -* Issues: https://github.com/hyperpolymath/ECOSYSTEM.scm/issues +* ECOSYSTEM.scm: https://github.com/hyperpolymath/ECOSYSTEM.scm +* STATE.scm: https://github.com/hyperpolymath/state.scm diff --git a/spec/family/SCM-FAMILY.adoc b/spec/family/SCM-FAMILY.adoc new file mode 100644 index 0000000..cf5a3bd --- /dev/null +++ b/spec/family/SCM-FAMILY.adoc @@ -0,0 +1,423 @@ += The SCM Format Family +:author: Jonathan D.A. Jewell +:revdate: 2025-12-15 +:toc: +:toclevels: 3 +:sectnums: +:icons: font + +== Overview + +The **SCM Format Family** is a collection of declarative S-expression formats designed to capture different dimensions of software development context. Each format addresses a specific domain while sharing common syntax, conventions, and tooling infrastructure. + +[source] +---- +┌─────────────────────────────────────────────────────────────────┐ +│ SCM Format Family │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────┐ │ +│ │ STATE.scm │ │ ECOSYSTEM.scm │ │ Future... │ │ +│ │ │ │ │ │ │ │ +│ │ Session State │ │ Project Context │ │ BUILD.scm? │ │ +│ │ Conversation │ │ Relationships │ │ CONFIG.scm? │ │ +│ │ Progress │ │ Boundaries │ │ │ │ +│ └────────┬────────┘ └────────┬────────┘ └──────┬──────┘ │ +│ │ │ │ │ +│ └──────────────────────┼─────────────────────┘ │ +│ │ │ +│ ┌─────────────┴─────────────┐ │ +│ │ Shared Primitives │ │ +│ │ Common ABNF Core │ │ +│ │ Unified Media Types │ │ +│ └───────────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +---- + +== Family Members + +=== STATE.scm + +**Domain:** AI Conversation Session State + +**Purpose:** Checkpoint and restore AI conversation context across sessions. Preserves user preferences, project progress, decision queues, and session history. + +**Key Forms:** +[source,scheme] +---- +(state + (metadata ...) ; Version, timestamps, generator + (user ...) ; Profile, preferences, values + (session ...) ; Conversation ID, tokens, messages + (focus ...) ; Current project, phase, deadlines + (projects ...) ; Full project catalogue with status + (history ...) ; Snapshots for velocity tracking + (next-actions ...)) ; Prioritised task queue +---- + +**Repository:** https://github.com/hyperpolymath/state.scm + +**Media Type:** `application/vnd.state+scm` + +=== ECOSYSTEM.scm + +**Domain:** Project Ecosystem Context + +**Purpose:** Describe software project relationships, boundaries, and position within the broader ecosystem. + +**Key Forms:** +[source,scheme] +---- +(ecosystem + (version ...) ; Document version + (name ...) ; Project name + (type ...) ; Category (library, app, etc.) + (purpose ...) ; Concise description + (position-in-ecosystem ...) + (related-projects ...) ; Typed relationships + (what-this-is ...) + (what-this-is-not ...)) +---- + +**Repository:** https://github.com/hyperpolymath/ECOSYSTEM.scm + +**Media Type:** `application/vnd.ecosystem+scm` + +=== Future Members + +Potential future family members under consideration: + +[cols="2,3,3"] +|=== +| Format | Domain | Purpose + +| `BUILD.scm` +| Build Configuration +| Declarative build recipes (alternative to justfile) + +| `CONFIG.scm` +| Application Config +| Runtime configuration with schema validation + +| `DEPLOY.scm` +| Deployment Context +| Environment, secrets references, infrastructure + +| `REVIEW.scm` +| Code Review State +| Review comments, decisions, approval workflow +|=== + +== Design Principles + +The SCM family shares these design principles: + +=== 1. Human Readability First + +S-expressions were chosen because they are: +- Self-explanatory without documentation +- Editable in any text editor +- Naturally hierarchical +- Comment-friendly + +=== 2. Version Control Friendly + +All formats: +- Produce meaningful diffs +- Avoid unnecessary ordering changes +- Use multiline strings for prose +- Support comments for context + +=== 3. Minimal Required Fields + +Each format defines only essential required fields. Rich metadata is available but optional, reducing adoption friction. + +=== 4. Extensibility + +All formats support vendor extensions via `x-` prefixed fields: + +[source,scheme] +---- +(ecosystem + (name "my-project") + (x-acme-internal-id "PRJ-12345") ; Vendor extension + (x-exp-maintainers ("alice"))) ; Experimental +---- + +=== 5. Tooling Compatibility + +Standard S-expression parsers can read all family formats. No custom syntax extensions are required. + +== Shared Infrastructure + +=== Common ABNF Core + +All SCM formats share a common ABNF foundation: + +[source,abnf] +---- +; See spec/family/scm-core.abnf for full grammar + +; Shared primitives +string = DQUOTE *string-char DQUOTE +identifier = ALPHA *( ALPHA / DIGIT / "-" / "_" ) +url-string = string ; Valid URI per RFC 3986 +semver = string ; Semantic versioning 2.0.0 + +; Shared constructs +comment = ";" *VCHAR ( LF / CR / CRLF ) +extension-field = "(" "x-" identifier 1*WSP sexp ")" +---- + +=== Unified Media Type Structure + +All family media types follow the pattern: + +`application/vnd.+scm` + +[cols="2,3"] +|=== +| Format | Media Type + +| STATE.scm +| `application/vnd.state+scm` + +| ECOSYSTEM.scm +| `application/vnd.ecosystem+scm` + +| Future +| `application/vnd.+scm` +|=== + +=== File Naming Conventions + +[cols="2,2,3"] +|=== +| Pattern | Example | Usage + +| `.scm` +| `ECOSYSTEM.scm` +| Repository root (canonical) + +| `*..scm` +| `myproject.ecosystem.scm` +| Multiple files, subdirectories + +| `*.` +| `myproject.ecosystem` +| Short form (alternative) +|=== + +== Integration Patterns + +=== Cross-Referencing + +Formats can reference each other: + +[source,scheme] +---- +;; In STATE.scm +(state + (metadata + (ecosystem-ref "https://github.com/org/project/ECOSYSTEM.scm")) + ...) + +;; In ECOSYSTEM.scm +(ecosystem + (specification + (related-formats + (format + (name "STATE.scm") + (purpose "Session state for this project") + (location "./STATE.scm")))) + ...) +---- + +=== Embedding + +Smaller formats may be embedded within larger ones: + +[source,scheme] +---- +(state + (metadata ...) + (embedded-ecosystem ; Full ECOSYSTEM.scm content + (ecosystem + (name "project-name") + ...))) +---- + +=== Tooling Discovery + +Tools can discover SCM files via: + +1. **Filename:** Look for `*.scm` matching known patterns +2. **Content:** Parse and check for known root forms (`state`, `ecosystem`) +3. **Media type:** HTTP `Content-Type` header for served files + +== Standards Strategy + +=== Unified IETF Approach + +The SCM family will pursue standardisation as a coordinated set: + +1. **Individual I-Ds:** Each format has its own Internet-Draft +2. **Family Overview:** Shared document describing the family +3. **Common Registration:** Coordinated IANA media type registration + +=== Timeline + +[source] +---- +2025 Q4: Individual format specifications complete ✓ +2026 Q1: Shared infrastructure and integration +2026 Q2: Community review and implementations +2026 Q3: IETF submission (coordinated) +2026 Q4: RFC publication target +---- + +=== IANA Registration Block + +Request registration of the following media type family: + +[cols="2,3"] +|=== +| Media Type | Specification + +| `application/vnd.state+scm` +| draft-jewell-state-scm + +| `application/vnd.ecosystem+scm` +| draft-jewell-ecosystem-scm + +| `application/vnd.scm` (reserved) +| Future family container format +|=== + +== Implementations + +=== Reference Implementations + +Recommended implementation languages: + +[cols="2,2,3"] +|=== +| Language | Priority | Notes + +| Rust +| Primary +| Reference implementations, CLI tools + +| TypeScript +| Primary +| Web tooling, VS Code extensions + +| Guile Scheme +| High +| Native format, REPL integration + +| Python +| Medium +| Scripting, data analysis + +| Go +| Medium +| Cloud tooling, CI/CD +|=== + +=== Shared Parser Library + +A shared parser library will provide: + +[source,rust] +---- +// Hypothetical API +use scm_family::{parse, Format}; + +let doc = parse(content)?; + +match doc.format() { + Format::State => handle_state(doc.as_state()?), + Format::Ecosystem => handle_ecosystem(doc.as_ecosystem()?), + Format::Unknown(name) => warn!("Unknown format: {}", name), +} +---- + +== Governance + +=== Maintainership + +* **Family Steward:** Jonathan D.A. Jewell +* **Individual Formats:** May have additional maintainers +* **Changes:** Via GitHub PRs with review + +=== Versioning + +Each format is versioned independently using Semantic Versioning: + +* **Major:** Breaking changes to required fields or semantics +* **Minor:** New optional fields or capabilities +* **Patch:** Clarifications, typo fixes + +The family itself has a coordination version for shared infrastructure. + +=== Contribution + +Contributions welcome via: + +* https://github.com/hyperpolymath/state.scm +* https://github.com/hyperpolymath/ECOSYSTEM.scm + +== Appendix: Why S-Expressions? + +=== Comparison with Alternatives + +[cols="2,1,1,1,1"] +|=== +| Criterion | S-expr | JSON | YAML | TOML + +| Human readable +| ✓✓ +| ✓ +| ✓✓ +| ✓✓ + +| Comments +| ✓ +| ✗ +| ✓ +| ✓ + +| Multiline strings +| ✓ +| Escape +| ✓✓ +| ✓ + +| Nesting clarity +| ✓✓ +| ✓ +| Indent +| ✓ + +| Parser simplicity +| ✓✓ +| ✓ +| Complex +| ✓ + +| Homoiconicity +| ✓✓ +| ✗ +| ✗ +| ✗ +|=== + +=== Homoiconicity Advantage + +S-expressions represent both data and code uniformly. This enables: + +* **Macro expansion:** Transform documents programmatically +* **REPL integration:** Load and query in Scheme/Lisp REPLs +* **Self-description:** Formats can describe their own grammar diff --git a/spec/family/scm-core.abnf b/spec/family/scm-core.abnf new file mode 100644 index 0000000..c0ab2ee --- /dev/null +++ b/spec/family/scm-core.abnf @@ -0,0 +1,262 @@ +; SCM Format Family - Shared ABNF Core +; SPDX-License-Identifier: MIT +; SPDX-FileCopyrightText: 2025 Jonathan D.A. Jewell +; +; This file defines the common ABNF primitives shared by all SCM family +; formats (STATE.scm, ECOSYSTEM.scm, and future members). +; +; Conformant implementations MUST support these primitives. +; Individual format specifications MAY extend but MUST NOT contradict. +; +; Version: 1.0.0 + +; ============================================================================= +; DOCUMENT STRUCTURE +; ============================================================================= + +; Generic SCM document - specific formats constrain the root-form +scm-document = *comment root-form *comment + +root-form = "(" format-identifier 1*WSP form-body ")" + +format-identifier = "state" ; STATE.scm + / "ecosystem" ; ECOSYSTEM.scm + / identifier ; Future formats + +form-body = *( form / comment ) + +; ============================================================================= +; S-EXPRESSION PRIMITIVES +; ============================================================================= + +sexp = atom / list / string + +atom = identifier / number / boolean / keyword + +list = "(" *( sexp / WSP / comment ) ")" + +; ============================================================================= +; IDENTIFIERS +; ============================================================================= + +identifier = identifier-start *identifier-char + +identifier-start = ALPHA / "_" + +identifier-char = ALPHA / DIGIT / "-" / "_" / "." / "/" + +; Special identifiers +keyword = ":" identifier + +; ============================================================================= +; STRINGS +; ============================================================================= + +string = DQUOTE *string-char DQUOTE + +string-char = unescaped-char / escaped-char + +unescaped-char = %x20-21 ; space through ! + / %x23-5B ; # through [ + / %x5D-7E ; ] through ~ + / utf8-char ; Non-ASCII UTF-8 + +escaped-char = "\" escape-code + +escape-code = DQUOTE ; \" quotation mark + / "\" ; \\ reverse solidus + / "/" ; \/ solidus (optional) + / "b" ; \b backspace + / "f" ; \f form feed + / "n" ; \n line feed + / "r" ; \r carriage return + / "t" ; \t tab + / "u" 4HEXDIG ; \uXXXX unicode + +; Multiline strings use the same syntax +; Implementations SHOULD preserve internal whitespace +multiline-string = string + +; ============================================================================= +; NUMBERS +; ============================================================================= + +number = integer / decimal / scientific + +integer = [ "-" / "+" ] 1*DIGIT + +decimal = [ "-" / "+" ] 1*DIGIT "." 1*DIGIT + +scientific = decimal ( "e" / "E" ) [ "-" / "+" ] 1*DIGIT + +; ============================================================================= +; BOOLEANS +; ============================================================================= + +boolean = true-val / false-val + +true-val = "#t" / "#true" / "#T" / "#TRUE" + +false-val = "#f" / "#false" / "#F" / "#FALSE" + +; ============================================================================= +; COMMON FORM PATTERNS +; ============================================================================= + +; Named form: (name value) +named-form = "(" identifier 1*WSP sexp ")" + +; Property form: (key value) +property-form = "(" identifier 1*WSP sexp ")" + +; List form: (name item*) +list-form = "(" identifier *( WSP sexp ) ")" + +; Extension form: (x-vendor-field value) +extension-form = "(" extension-id 1*WSP sexp ")" + +extension-id = "x-" 1*( ALPHA / DIGIT / "-" ) + +; ============================================================================= +; SEMANTIC STRING TYPES +; ============================================================================= + +; URI per RFC 3986 +uri-string = string +; Constraint: MUST be valid URI + +; Semantic Version per semver.org 2.0.0 +semver-string = string +; Constraint: MUST match semver pattern + +; ISO 8601 datetime +datetime-string = string +; Constraint: MUST be valid ISO 8601 + +; Media type per RFC 6838 +mediatype-string = string +; Constraint: MUST be valid media type + +; SPDX license expression +spdx-string = string +; Constraint: SHOULD be valid SPDX expression + +; ============================================================================= +; COMMENTS +; ============================================================================= + +comment = line-comment / block-comment + +; Line comment: semicolon to end of line +line-comment = ";" *line-char line-end + +line-char = %x20-7E / utf8-char + +line-end = LF / CR / CRLF / EOF + +EOF = "" ; End of input + +; Block comment: #| ... |# (nestable) +block-comment = "#|" block-content "|#" + +block-content = *( block-text / block-comment ) + +block-text = 1*( %x00-7B / %x7D-10FFFF ) ; Any except | followed by # + / "|" %x00-22 + / "|" %x24-10FFFF + +; ============================================================================= +; WHITESPACE +; ============================================================================= + +WSP = 1*ws-char + +ws-char = SP / HTAB / LF / CR + +SP = %x20 ; Space +HTAB = %x09 ; Horizontal tab +LF = %x0A ; Line feed +CR = %x0D ; Carriage return +CRLF = CR LF ; Windows newline + +; ============================================================================= +; UTF-8 ENCODING +; ============================================================================= + +; UTF-8 continuation bytes +utf8-char = utf8-2 / utf8-3 / utf8-4 + +utf8-2 = %xC2-DF utf8-tail + +utf8-3 = %xE0 %xA0-BF utf8-tail + / %xE1-EC 2utf8-tail + / %xED %x80-9F utf8-tail + / %xEE-EF 2utf8-tail + +utf8-4 = %xF0 %x90-BF 2utf8-tail + / %xF1-F3 3utf8-tail + / %xF4 %x80-8F 2utf8-tail + +utf8-tail = %x80-BF + +; ============================================================================= +; CORE ABNF RULES (RFC 5234) +; ============================================================================= + +ALPHA = %x41-5A / %x61-7A ; A-Z / a-z + +DIGIT = %x30-39 ; 0-9 + +HEXDIG = DIGIT + / "A" / "B" / "C" / "D" / "E" / "F" + / "a" / "b" / "c" / "d" / "e" / "f" + +DQUOTE = %x22 ; " + +VCHAR = %x21-7E ; Visible characters + +; ============================================================================= +; SEMANTIC CONSTRAINTS (non-ABNF, for implementers) +; ============================================================================= + +; 1. Documents MUST be valid UTF-8 +; 2. The root-form identifier determines the format type +; 3. Extension fields (x-*) MUST be ignored if not understood +; 4. Unknown forms within known containers SHOULD be preserved +; 5. Parsers SHOULD limit nesting depth (recommended: 100) +; 6. Parsers SHOULD limit document size (recommended: 10MB) +; 7. String content MUST NOT contain unescaped control characters +; except LF and HTAB (which are permitted in multiline strings) + +; ============================================================================= +; INTEROPERABILITY NOTES +; ============================================================================= + +; JSON Mapping: +; - Lists become arrays +; - Named forms become objects with single key +; - Atoms become strings, numbers, or booleans +; - Comments are lost +; - Extensions map to "x-*" keys + +; Round-trip: +; - Implementations SHOULD preserve comments when possible +; - Whitespace within strings MUST be preserved +; - Formatting whitespace MAY be normalised + +; ============================================================================= +; EXAMPLES +; ============================================================================= + +; Minimal valid documents: +; +; (state (metadata (version "2.0"))) +; +; (ecosystem (version "1.0.0") (name "x") (type "lib") (purpose "y")) + +; Extension usage: +; +; (ecosystem +; (name "project") +; (x-acme-id "12345") ; Vendor extension +; (x-exp-feature #t)) ; Experimental extension diff --git a/spec/family/scm-family.schema.json b/spec/family/scm-family.schema.json new file mode 100644 index 0000000..bfc5943 --- /dev/null +++ b/spec/family/scm-family.schema.json @@ -0,0 +1,308 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://scm.family/schema/1.0.0/scm-family.schema.json", + "title": "SCM Format Family Schema", + "description": "Unified JSON Schema for validating any SCM Format Family document (STATE.scm, ECOSYSTEM.scm, etc.)", + + "oneOf": [ + { "$ref": "#/$defs/stateDocument" }, + { "$ref": "#/$defs/ecosystemDocument" } + ], + + "$defs": { + "stateDocument": { + "type": "object", + "description": "STATE.scm document for session state persistence", + "required": ["metadata"], + "properties": { + "_format": { + "const": "state", + "description": "Format identifier (implicit in S-expression, explicit in JSON)" + }, + "metadata": { "$ref": "#/$defs/stateMetadata" }, + "user": { "$ref": "#/$defs/stateUser" }, + "session": { "$ref": "#/$defs/stateSession" }, + "focus": { "$ref": "#/$defs/stateFocus" }, + "projects": { + "type": "array", + "items": { "$ref": "#/$defs/stateProject" } + }, + "history": { "$ref": "#/$defs/stateHistory" }, + "next-actions": { + "type": "array", + "items": { "$ref": "#/$defs/stateAction" } + }, + "issues": { + "type": "array", + "items": { "$ref": "#/$defs/stateIssue" } + }, + "decisions": { + "type": "array", + "items": { "$ref": "#/$defs/stateDecision" } + } + }, + "patternProperties": { + "^x-": { "description": "Extension field" } + }, + "additionalProperties": true + }, + + "ecosystemDocument": { + "type": "object", + "description": "ECOSYSTEM.scm document for project ecosystem context", + "required": ["version", "name", "type", "purpose"], + "properties": { + "_format": { + "const": "ecosystem", + "description": "Format identifier (implicit in S-expression, explicit in JSON)" + }, + "version": { "$ref": "#/$defs/semver" }, + "name": { "type": "string", "minLength": 1 }, + "type": { "$ref": "#/$defs/projectType" }, + "purpose": { "type": "string", "minLength": 1 }, + "family": { "$ref": "#/$defs/familyMembership" }, + "position-in-ecosystem": { "type": "string" }, + "related-projects": { + "type": "array", + "items": { "$ref": "#/$defs/relatedProject" } + }, + "what-this-is": { "type": "string" }, + "what-this-is-not": { "type": "string" }, + "specification": { "$ref": "#/$defs/specificationMeta" }, + "standards-track": { "$ref": "#/$defs/standardsTrack" }, + "future-integration": { "type": "string" } + }, + "patternProperties": { + "^x-": { "description": "Extension field" } + }, + "additionalProperties": true + }, + + "stateMetadata": { + "type": "object", + "required": ["version"], + "properties": { + "version": { "type": "string" }, + "created": { "$ref": "#/$defs/datetime" }, + "modified": { "$ref": "#/$defs/datetime" }, + "generator": { "type": "string" }, + "ecosystem-ref": { "type": "string", "format": "uri-reference" } + } + }, + + "stateUser": { + "type": "object", + "properties": { + "name": { "type": "string" }, + "roles": { "type": "array", "items": { "type": "string" } }, + "preferences": { "type": "object" }, + "values": { "type": "array", "items": { "type": "string" } } + } + }, + + "stateSession": { + "type": "object", + "properties": { + "conversation-id": { "type": "string" }, + "message-count": { "type": "integer", "minimum": 0 }, + "token-limit": { "type": "integer" }, + "tokens-used": { "type": "integer" } + } + }, + + "stateFocus": { + "type": "object", + "properties": { + "project": { "type": "string" }, + "phase": { "type": "string" }, + "deadline": { "$ref": "#/$defs/datetime" }, + "blockers": { "type": "array", "items": { "type": "string" } } + } + }, + + "stateProject": { + "type": "object", + "required": ["name", "status"], + "properties": { + "name": { "type": "string" }, + "status": { + "type": "string", + "enum": ["in-progress", "blocked", "paused", "complete", "abandoned"] + }, + "completion": { "type": "number", "minimum": 0, "maximum": 100 }, + "category": { "type": "string" }, + "phase": { "type": "string" }, + "dependencies": { "type": "array", "items": { "type": "string" } }, + "blockers": { "type": "array", "items": { "type": "string" } }, + "next-actions": { "type": "array", "items": { "type": "string" } } + } + }, + + "stateHistory": { + "type": "object", + "properties": { + "snapshots": { + "type": "array", + "items": { "$ref": "#/$defs/stateSnapshot" } + } + } + }, + + "stateSnapshot": { + "type": "object", + "properties": { + "timestamp": { "$ref": "#/$defs/datetime" }, + "projects": { "type": "object" } + } + }, + + "stateAction": { + "type": "object", + "required": ["description"], + "properties": { + "description": { "type": "string" }, + "priority": { "type": "string", "enum": ["critical", "high", "medium", "low"] }, + "deadline": { "$ref": "#/$defs/datetime" }, + "project": { "type": "string" } + } + }, + + "stateIssue": { + "type": "object", + "required": ["id", "description"], + "properties": { + "id": { "type": "string" }, + "description": { "type": "string" }, + "severity": { "type": "string", "enum": ["critical", "high", "medium", "low"] }, + "status": { "type": "string", "enum": ["open", "investigating", "resolved", "wontfix"] } + } + }, + + "stateDecision": { + "type": "object", + "required": ["id", "question"], + "properties": { + "id": { "type": "string" }, + "question": { "type": "string" }, + "options": { "type": "array", "items": { "type": "string" } }, + "status": { "type": "string", "enum": ["open", "decided", "deferred"] }, + "decision": { "type": "string" } + } + }, + + "familyMembership": { + "type": "object", + "properties": { + "name": { "type": "string" }, + "role": { "type": "string", "enum": ["family-member", "family-lead"] }, + "family-spec": { "type": "string" }, + "shared-grammar": { "type": "string" }, + "siblings": { + "type": "array", + "items": { "$ref": "#/$defs/familySibling" } + } + } + }, + + "familySibling": { + "type": "object", + "required": ["name", "domain"], + "properties": { + "name": { "type": "string" }, + "domain": { "type": "string" }, + "media-type": { "$ref": "#/$defs/mediaType" } + } + }, + + "relatedProject": { + "type": "object", + "required": ["name", "relationship"], + "properties": { + "name": { "type": "string", "minLength": 1 }, + "url": { "type": "string", "format": "uri" }, + "relationship": { "$ref": "#/$defs/relationshipType" }, + "description": { "type": "string" }, + "differentiation": { "type": "string" }, + "integration-notes": { "type": "string" } + }, + "patternProperties": { + "^x-": { "description": "Extension field" } + } + }, + + "specificationMeta": { + "type": "object", + "properties": { + "format": { "type": "string" }, + "encoding": { "type": "string", "enum": ["UTF-8"] }, + "file-extension": { "type": "string" }, + "media-type": { "$ref": "#/$defs/mediaType" }, + "grammar-definition": { "type": "string" }, + "shared-grammar": { "type": "string" }, + "json-schema": { "type": "string" }, + "internet-draft": { "type": "string" }, + "family-spec": { "type": "string" } + } + }, + + "standardsTrack": { + "type": "object", + "properties": { + "body": { "type": "string" }, + "type": { "type": "string" }, + "status": { "type": "string", "enum": ["draft", "submitted", "review", "approved", "published"] }, + "coordination": { "type": "string" }, + "roadmap": { "type": "string" } + } + }, + + "projectType": { + "type": "string", + "examples": [ + "library", + "application", + "service", + "specification", + "framework", + "tool", + "plugin", + "extension", + "template" + ] + }, + + "relationshipType": { + "type": "string", + "examples": [ + "consumer", + "producer", + "sibling", + "sibling-standard", + "complementary", + "alternative", + "inspiration", + "fork", + "upstream", + "downstream", + "potential-consumer", + "deprecated-by", + "deprecates" + ] + }, + + "semver": { + "type": "string", + "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$" + }, + + "datetime": { + "type": "string", + "format": "date-time" + }, + + "mediaType": { + "type": "string", + "pattern": "^[a-z]+/[a-z0-9.+-]+$" + } + } +}