




Internet Engineering Task Force                               J. Jewell
Internet-Draft                                              Independent
Intended status: Informational                           15 December 2025
Expires: 17 June 2026


                          The ECOSYSTEM.scm Format
                       draft-jewell-ecosystem-scm-00

Abstract

   This document defines ECOSYSTEM.scm, a declarative S-expression
   format for describing software project ecosystems and inter-project
   relationships.  The format enables projects to formally declare their
   position within a broader ecosystem, relationships to other projects,
   and boundaries of responsibility.  ECOSYSTEM.scm is designed to be
   human-readable, version-control friendly, and machine-parseable.

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at https://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on 17 June 2026.

Copyright Notice

   Copyright (c) 2025 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (https://trustee.ietf.org/license-PMPL--1.0) in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.


Table of Contents

   1.  Introduction
       1.1.  Motivation
       1.2.  Design Goals
       1.3.  Conventions and Terminology
   2.  Format Overview
       2.1.  S-Expression Syntax
       2.2.  Document Structure
       2.3.  Character Encoding
   3.  Core Elements
       3.1.  ecosystem (Root Element)
       3.2.  version
       3.3.  name
       3.4.  type
       3.5.  purpose
   4.  Descriptive Elements
       4.1.  position-in-ecosystem
       4.2.  what-this-is
       4.3.  what-this-is-not
       4.4.  future-integration
   5.  Related Projects
       5.1.  related-projects Container
       5.2.  project Element
       5.3.  Relationship Types
   6.  Specification Metadata
       6.1.  specification Container
       6.2.  Metadata Fields
   7.  Extension Mechanism
       7.1.  Vendor Extensions
       7.2.  Experimental Extensions
   8.  Processing Model
       8.1.  Parsing
       8.2.  Validation
       8.3.  Unknown Elements
   9.  Security Considerations
   10. IANA Considerations
       10.1. Media Type Registration
       10.2. File Extension
   11. References
       11.1. Normative References
       11.2. Informative References
   Appendix A.  Complete ABNF Grammar
   Appendix B.  JSON Mapping
   Appendix C.  Example Documents
   Acknowledgments
   Author's Address


1.  Introduction

1.1.  Motivation

   Modern software development increasingly relies on ecosystems of
   interrelated projects.  Libraries depend on frameworks, applications
   consume services, and specifications guide implementations.  However,
   no standard format exists for formally declaring these relationships
   and project boundaries.

   Projects often include informal documentation describing what they
   are and are not, but this information is typically buried in README
   files in varied formats.  ECOSYSTEM.scm provides a structured,
   machine-readable format for this metadata.

   Key use cases include:

   -  Automated dependency and relationship mapping
   -  Documentation generation showing project context
   -  Ecosystem visualization tools
   -  Disambiguation between similar projects
   -  Integration planning and compatibility assessment

1.2.  Design Goals

   ECOSYSTEM.scm was designed with the following goals:

   1.  Human Readability: The format should be easily readable and
       writable by humans without specialized tools.

   2.  Version Control Friendly: Changes should produce meaningful
       diffs in version control systems.

   3.  Machine Parseable: Standard S-expression parsers should be able
       to process the format without modification.

   4.  Minimal Required Fields: Only essential information should be
       mandatory; rich metadata should be optional.

   5.  Extensibility: The format should allow vendor-specific and
       experimental extensions without breaking compatibility.

   6.  Self-Documenting: Relationship types and field names should be
       descriptive enough to understand without constant reference to
       this specification.

1.3.  Conventions and Terminology

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
   "OPTIONAL" in this document are to be interpreted as described in
   BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
   capitals, as shown here.

   S-expression:  A notation for nested list data, originating from
                  the Lisp programming language family.

   Form:          An S-expression representing a complete syntactic
                  unit, typically a parenthesized list beginning with
                  an identifier.

   Ecosystem:     A collection of interrelated software projects that
                  work together or serve related purposes.


2.  Format Overview

2.1.  S-Expression Syntax

   ECOSYSTEM.scm uses S-expression (symbolic expression) syntax.  An
   S-expression is either an atom (identifier, string, number, or
   boolean) or a list of S-expressions enclosed in parentheses.

   Example S-expressions:

      identifier
      "a string value"
      42
      (list of items)
      (nested (lists (work too)))

   Comments begin with a semicolon and extend to end of line:

      ; This is a comment
      (form  ; inline comment
        (nested-form))

   Block comments use the #| ... |# syntax and may nest:

      #| This is a
         block comment |#

2.2.  Document Structure

   An ECOSYSTEM.scm document consists of:

   1.  Optional leading comments (typically license headers)
   2.  Exactly one 'ecosystem' form
   3.  Optional trailing comments

   Minimal valid document:

      (ecosystem
        (version "1.0.0")
        (name "my-project")
        (type "library")
        (purpose "A brief description of the project"))

2.3.  Character Encoding

   ECOSYSTEM.scm documents MUST be encoded in UTF-8 [RFC3629].
   Implementations MUST reject documents with invalid UTF-8 sequences.

   The Byte Order Mark (BOM) SHOULD NOT be used but MUST be tolerated
   by parsers if present.


3.  Core Elements

   These elements are REQUIRED in every ECOSYSTEM.scm document.

3.1.  ecosystem (Root Element)

   The root element containing all other elements.

   Syntax:  (ecosystem <body>)

   The body consists of zero or more forms and comments.  Order of
   child elements is not significant.

3.2.  version

   The version of this ECOSYSTEM.scm document's content (not the
   format version).

   Syntax:  (version <string>)

   The version string MUST follow Semantic Versioning 2.0.0 [SEMVER].
   Pre-release and build metadata suffixes are permitted.

   Examples:

      (version "1.0.0")
      (version "2.1.0-alpha.1")
      (version "0.1.0-draft")

3.3.  name

   The canonical name of the project.

   Syntax:  (name <string>)

   The name SHOULD match the project's primary identifier (e.g.,
   package name, repository name).

   Example:

      (name "mobile-ai-orchestrator")

3.4.  type

   The category of software this project represents.

   Syntax:  (type <string>)

   Recommended values:

   -  "library"        A reusable code package
   -  "application"    An end-user application
   -  "service"        A network service or daemon
   -  "specification"  A format or protocol specification
   -  "framework"      An application framework
   -  "tool"           A developer or system tool
   -  "plugin"         An extension to another system
   -  "extension"      Similar to plugin
   -  "template"       A project template or scaffold

   Custom values MAY be used but SHOULD be documented.

3.5.  purpose

   A concise description of the project's purpose.

   Syntax:  (purpose <string>)

   The purpose SHOULD be one to three sentences describing the primary
   function of the project.

   Example:

      (purpose "Platform-agnostic AI routing decisions for
                constrained devices")


4.  Descriptive Elements

   These elements are OPTIONAL but RECOMMENDED for complete ecosystem
   documentation.

4.1.  position-in-ecosystem

   Describes where this project fits in the broader ecosystem.

   Syntax:  (position-in-ecosystem <string>)

   This field explains the project's role relative to other projects,
   its layer in the stack, and its intended consumers.

   Example:

      (position-in-ecosystem
        "This is the LIBRARY layer - provides routing intelligence.
         Applications like neurophone consume this library.
         Does NOT do inference - tells you WHERE to run inference.")

4.2.  what-this-is

   A detailed explanation of what the project provides.

   Syntax:  (what-this-is <string>)

   This field enumerates capabilities, components, and design
   principles.

4.3.  what-this-is-not

   An explicit statement of what the project does NOT do.

   Syntax:  (what-this-is-not <string>)

   This field is crucial for disambiguation, especially when similar
   projects exist.  It prevents scope creep and sets clear boundaries.

   Example:

      (what-this-is-not
        "- NOT an Android app (see neurophone for that)
         - NOT a complete AI system (just routing decisions)
         - NOT inference engine (bring your own llama.cpp/Claude)
         - NOT sensor processing (bring your own sensors)")

4.4.  future-integration

   Describes planned or potential future integrations.

   Syntax:  (future-integration <string>)

   This field documents integration roadmap without making commitments.


5.  Related Projects

5.1.  related-projects Container

   Contains zero or more project elements describing related projects.

   Syntax:  (related-projects <project>*)

5.2.  project Element

   Describes a single related project.

   Syntax:  (project <field>+)

   Required fields:
   -  name: Project name
   -  relationship: Type of relationship

   Optional fields:
   -  url: Project URL
   -  description: Brief description
   -  differentiation: How projects differ
   -  integration-notes: Integration guidance

   Example:

      (project
        (name "neurophone")
        (url "https://github.com/hyperpolymath/neurophone")
        (relationship "consumer")
        (description "Android application that could use this library")
        (differentiation
          "neurophone = Android app with sensors, LSM, ESN, JNI
           this = Platform-agnostic routing library"))

5.3.  Relationship Types

   Recommended relationship type values:

   consumer:           The related project uses this project
   producer:           This project uses the related project
   sibling:            Same organization or ecosystem
   sibling-standard:   Related specification or standard
   complementary:      Works alongside this project
   alternative:        Competing or alternative solution
   inspiration:        Design or conceptual influence
   fork:               This project is forked from related
   upstream:           The original/source project
   downstream:         A derivative of this project
   potential-consumer: May use this project in future
   deprecated-by:      This project is superseded by related
   deprecates:         This project supersedes related

   Custom relationship types MAY be used for domain-specific
   relationships.


6.  Specification Metadata

6.1.  specification Container

   Contains technical metadata about the format specification itself.

   Syntax:  (specification <field>*)

   This element is primarily used in self-describing specification
   documents.

6.2.  Metadata Fields

   format:             The syntax format (e.g., "S-expression")
   encoding:           Character encoding (e.g., "UTF-8")
   file-extension:     Standard file extension (e.g., ".scm")
   media-type:         IANA media type
   grammar-definition: Path to formal grammar
   json-schema:        Path to JSON Schema


7.  Extension Mechanism

7.1.  Vendor Extensions

   Vendor-specific extensions MUST use the "x-" prefix followed by a
   vendor identifier.

   Syntax:  (x-<vendor>-<field> <value>)

   Example:

      (x-acme-internal-id "PRJ-12345")
      (x-github-topics ("rust" "ai" "routing"))

7.2.  Experimental Extensions

   Experimental extensions that may become standard SHOULD use "x-exp-"
   prefix.

   Example:

      (x-exp-maintainers ("alice" "bob"))

   Parsers MUST ignore unknown extensions without error.


8.  Processing Model

8.1.  Parsing

   Implementations SHOULD use a standard S-expression parser.  The
   parser MUST handle:

   -  Nested parentheses to arbitrary depth
   -  Double-quoted strings with escape sequences
   -  Line comments (;) and block comments (#| |#)
   -  UTF-8 encoded content

8.2.  Validation

   After parsing, implementations SHOULD validate:

   1.  Exactly one 'ecosystem' root element exists
   2.  All required fields (version, name, type, purpose) are present
   3.  Version follows Semantic Versioning format
   4.  URLs are valid URIs per RFC 3986

8.3.  Unknown Elements

   Parsers MUST NOT reject documents containing unknown elements.
   Unknown elements SHOULD be preserved during round-trip processing
   when possible.


9.  Security Considerations

   ECOSYSTEM.scm documents are declarative metadata and do not contain
   executable code.  However, implementations should consider:

   1.  URL Handling: URLs in 'url' fields should be validated before
       use to prevent SSRF attacks.

   2.  Denial of Service: Parsers should limit recursion depth and
       document size to prevent resource exhaustion.

   3.  Information Disclosure: ECOSYSTEM.scm may reveal internal
       project structure.  Authors should consider what information
       is appropriate for public documents.

   4.  Injection: When embedding ECOSYSTEM.scm content in other
       formats (HTML, JSON), proper escaping is required.


10. IANA Considerations

10.1. Media Type Registration

   This document requests registration of the following media type:

   Type name:  application

   Subtype name:  vnd.ecosystem+scm

   Required parameters:  None

   Optional parameters:

      charset:  Always UTF-8.  If specified, MUST be "utf-8".

   Encoding considerations:  8bit (UTF-8)

   Security considerations:  See Section 9

   Interoperability considerations:  None

   Published specification:  This document

   Applications that use this media type:

      Software development tools, documentation generators,
      dependency analyzers, ecosystem visualization tools.

   Fragment identifier considerations:  None defined

   Additional information:

      Deprecated alias names for this type:  None
      Magic number(s):  Documents typically begin with "(ecosystem"
      File extension(s):  .ecosystem.scm, .ecosystem
      Macintosh file type code(s):  None

   Person & email address to contact for further information:

      Jonathan D.A. Jewell

   Intended usage:  COMMON

   Restrictions on usage:  None

   Author:  Jonathan D.A. Jewell

   Change controller:  IETF

10.2. File Extension

   The recommended file extensions are:

   -  .ecosystem.scm (preferred, unambiguous)
   -  .ecosystem (alternative)
   -  ECOSYSTEM.scm (conventional filename for repository root)


11. References

11.1. Normative References

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <https://www.rfc-editor.org/info/rfc2119>.

   [RFC3629]  Yergeau, F., "UTF-8, a transformation format of ISO
              10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November
              2003, <https://www.rfc-editor.org/info/rfc3629>.

   [RFC3986]  Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
              Resource Identifier (URI): Generic Syntax", STD 66,
              RFC 3986, DOI 10.17487/RFC3986, January 2005,
              <https://www.rfc-editor.org/info/rfc3986>.

   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
              2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
              May 2017, <https://www.rfc-editor.org/info/rfc8174>.

   [SEMVER]   Preston-Werner, T., "Semantic Versioning 2.0.0",
              <https://semver.org/spec/v2.0.0.html>.

11.2. Informative References

   [RFC5545]  Desruisseaux, B., Ed., "Internet Calendaring and
              Scheduling Core Object Specification (iCalendar)",
              RFC 5545, DOI 10.17487/RFC5545, September 2009,
              <https://www.rfc-editor.org/info/rfc5545>.

   [RFC7946]  Butler, H., Daly, M., Doyle, A., Gillies, S., Hagen, S.,
              and T. Schaub, "The GeoJSON Format", RFC 7946,
              DOI 10.17487/RFC7946, August 2016,
              <https://www.rfc-editor.org/info/rfc7946>.


Appendix A.  Complete ABNF Grammar

   See the accompanying file ecosystem.abnf for the complete formal
   grammar in ABNF notation per RFC 5234.


Appendix B.  JSON Mapping

   ECOSYSTEM.scm documents MAY be represented in JSON for environments
   where S-expression parsers are unavailable.  The mapping is:

   -  The 'ecosystem' form becomes the root JSON object
   -  Nested forms become nested objects
   -  Lists become JSON arrays
   -  Strings remain strings
   -  Numbers remain numbers
   -  Booleans (#t/#f) become true/false

   Example:

      {
        "version": "1.0.0",
        "name": "my-project",
        "type": "library",
        "purpose": "Does something useful",
        "related-projects": [
          {
            "name": "other-project",
            "relationship": "sibling"
          }
        ]
      }

   A JSON Schema is provided in the accompanying file
   ecosystem.schema.json.


Appendix C.  Example Documents

C.1.  Minimal Document

      (ecosystem
        (version "1.0.0")
        (name "minimal-example")
        (type "library")
        (purpose "A minimal ECOSYSTEM.scm example"))

C.2.  Full Document

      See ECOSYSTEM.scm in the repository root for a comprehensive
      example demonstrating all features.


Acknowledgments

   The author thanks the contributors to the STATE.scm project for
   inspiration on declarative format design.


Author's Address

   Jonathan D.A. Jewell

   Email: (see repository)
   URI:   https://github.com/hyperpolymath/ECOSYSTEM.scm
