Current assets:
-
JSON Schema:
spec/ecosystem.schema.json -
Family shared grammar:
spec/family/scm-core.abnf -
IANA considerations:
spec/IANA-CONSIDERATIONS.adoc -
Roadmaps:
ROADMAP.adoc,STANDARDS-ROADMAP.adoc
Next actions:
-
Add worked examples in
spec/and README -
Define conformance tests and fixtures
-
Finalize media-type registration text
ECOSYSTEM.a2ml is a declarative A2ML (Annotated Markup Language) TOML-like key-value format for describing software project ecosystems and inter-project relationships. It is part of the A2ML Format Family.
The MVP v1.1 release is ready for handover:
-
Palimpsest Plasma
v1.1release bundle athttps://github.com/hyperpolymath/palimpsest-plasma/releases/tag/v1.1contains canonical PMPL-1.0 text, badge assets, MVP docs, and signature metadata. -
Audits
pmpl-verify/pmpl-audithave been run; logs live indocs/release-log.adocanddocs/release-notes.adocwithin the release bundle. -
Engineering handover briefing: share this README + release notes plus
mvp-v1.1-release.tar.gzto IO so they can continue the next project.
# ECOSYSTEM.a2ml
[ecosystem]
version = "1.0.0"
name = "my-project"
type = "library"
purpose = "Platform-agnostic AI routing decisions"
position-in-ecosystem = """
This is the LIBRARY layer - provides routing intelligence.
Applications consume this library for decision-making."""
what-this-is = "A Rust library that decides WHERE to run AI inference"
what-this-is-not = """
- NOT an application (just a library)
- NOT an inference engine (bring your own)"""
[ecosystem.related-projects.other-project]
url = "https://github.com/org/other-project"
relationship = "consumer"
description = "Uses this library for routing"ECOSYSTEM.a2ml is part of a family of declarative A2ML TOML-like key-value formats:
+-------------------------------------------------------------+
| A2ML Format Family |
+-------------------------------------------------------------+
| |
| +-----------------+ +-----------------+ |
| | STATE.a2ml |<------->| ECOSYSTEM.a2ml | |
| | | cross- | | |
| | Session State | ref | Project Context | |
| | Progress Track | | Relationships | |
| | Decision Queue | | Boundaries | |
| +--------+--------+ +--------+---------+ |
| | | |
| +-----------+---------------+ |
| | |
| +-----------+-----------+ |
| | Shared Foundation | |
| | Unified media types | |
| +-----------------------+ |
| |
+---------------------------------------------------------------+| Aspect | STATE.a2ml | ECOSYSTEM.a2ml |
|---|---|---|
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 |
|
|
See SCM-FAMILY.adoc for the complete family specification.
Modern software exists within ecosystems of interrelated projects. Yet no standard format exists to formally declare:
-
What a project is - and equally important, what it is not
-
Where it fits - its position in the broader ecosystem
-
How it relates - typed relationships to other projects
-
Where it’s going - future integration intentions
ECOSYSTEM.a2ml fills this gap with a human-readable, version-control friendly, machine-parseable TOML-like key-value format.
-
Automated dependency mapping - Understand project relationships at scale
-
Documentation generation - Create ecosystem visualisations
-
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.a2ml)
Place in your repository root:
# SPDX-License-Identifier: PMPL-1.0-or-later
# ECOSYSTEM.a2ml - Project ecosystem context
[ecosystem]
version = "1.0.0"
name = "your-project-name"
type = "library" # or: application, service, specification, framework, tool
purpose = "One sentence describing what this does"
what-this-is = "Detailed explanation of capabilities"
what-this-is-not = "Explicit boundaries and non-goals"[ecosystem.related-projects.upstream-lib]
url = "https://github.com/org/upstream-lib"
relationship = "producer"
description = "We depend on this library"
[ecosystem.related-projects.competing-tool]
relationship = "alternative"
differentiation = "We focus on X; they focus on Y"Reference your ECOSYSTEM.a2ml from STATE.a2ml for complete context:
# In your STATE.a2ml file
[state.metadata]
version = "2.0"
ecosystem-ref = "./ECOSYSTEM.a2ml"-
Syntax: TOML-like key-value (A2ML)
-
Encoding: UTF-8
-
Media Type:
application/vnd.ecosystem+a2ml -
File Extension:
.a2ml(conventionallyECOSYSTEM.a2ml)
| Field | Description |
|---|---|
|
Semantic version of document content |
|
Canonical project name |
|
Project category (library, application, service, etc.) |
|
Concise description (1-3 sentences) |
| Field | Description |
|---|---|
|
A2ML family membership declaration |
|
Where this project fits in the broader ecosystem |
|
List of related projects with typed relationships |
|
Detailed explanation of capabilities |
|
Explicit boundaries and non-goals |
|
Technical metadata (for spec documents) |
|
Standardisation status and roadmap |
|
Planned integrations |
| Type | Meaning |
|---|---|
|
Related project uses this project |
|
This project uses related project |
|
Same organisation or ecosystem |
|
Related specification (e.g., STATE.a2ml) |
|
Works alongside this project |
|
Competing or alternative solution |
|
Design influence |
|
Code lineage relationships |
|
May use in future |
|
Succession relationships |
ECOSYSTEM.a2ml is pursuing formal standardisation through the IETF Informational RFC track as part of a coordinated A2ML family submission.
| Deliverable | Location | Status |
|---|---|---|
Canonical specification |
|
Complete |
JSON Schema |
|
Complete |
Unified family schema |
|
Complete |
Internet-Draft |
|
Complete |
A2ML Family spec |
|
Complete |
IANA considerations |
|
Complete |
Standards roadmap |
|
Complete |
-
Strong precedent for data formats (GeoJSON RFC 7946, iCalendar RFC 5545)
-
Accessible, well-understood process
-
Free and volunteer-driven
-
Coordinated family submission for STATE.a2ml and ECOSYSTEM.a2ml
-
Leads to IANA media type registration
See STANDARDS-ROADMAP.adoc for the complete standardisation plan.
ecosystem-a2ml/
+-- ECOSYSTEM.a2ml # Canonical specification (self-describing)
+-- README.adoc # This file
+-- STANDARDS-ROADMAP.adoc # Unified family standardisation plan
+-- spec/
| +-- ecosystem.schema.json # Format-specific JSON Schema
| +-- IANA-CONSIDERATIONS.adoc
| +-- draft/
| | +-- draft-jewell-ecosystem-a2ml-00.txt
| +-- family/ # Shared A2ML family infrastructure
| +-- SCM-FAMILY.adoc # Family specification
| +-- scm-family.schema.json # Unified validation schema
+-- CONTRIBUTING.md
+-- CODE_OF_CONDUCT.md
+-- SECURITY.md
+-- LICENSE # PMPL-1.0Session state persistence for AI conversation continuity.
-
Repository: state-a2ml
-
Relationship:
sibling-standard -
Domain: Temporal context (sessions, progress, decisions)
-
Integration: Cross-reference via
ecosystem-refin STATE.a2ml metadata
Use together for complete context:
-
ECOSYSTEM.a2ml in repository root (static, versioned with code)
-
STATE.a2ml for session persistence (dynamic, conversation-specific)
See CONTRIBUTING.md for guidelines.
Palimpsest-MPL License v1.0 (PMPL-1.0) - see LICENSE