= ECOSYSTEM.a2ml
image:https://img.shields.io/badge/License-PMPL--1.0-blue.svg[License: PMPL-1.0,link="https://github.com/hyperpolymath/palimpsest-license"]




:author: Jonathan D.A. Jewell
:revdate: 2026-03-16
:toc:
:toclevels: 3
:sectnums:
:icons: font
:source-highlighter: rouge

== Overview

== Handover (2026-01-18)

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**.

== Handover Status (2026-01-20)

The MVP v1.1 release is ready for handover:

* Palimpsest Plasma `v1.1` release bundle at `https://github.com/hyperpolymath/palimpsest-plasma/releases/tag/v1.1` contains canonical PMPL-1.0 text, badge assets, MVP docs, and signature metadata.
* Audits `pmpl-verify`/`pmpl-audit` have been run; logs live in `docs/release-log.adoc` and `docs/release-notes.adoc` within the release bundle.
* Engineering handover briefing: share this README + release notes plus `mvp-v1.1-release.tar.gz` to IO so they can continue the next project.

[source,toml]
----
# 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"
----

== A2ML Format Family

ECOSYSTEM.a2ml is part of a family of declarative A2ML TOML-like key-value formats:

[source]
----
+-------------------------------------------------------------+
|                     A2ML Format Family                       |
+-------------------------------------------------------------+
|                                                               |
|  +-----------------+          +-----------------+            |
|  |   STATE.a2ml    |<------->|  ECOSYSTEM.a2ml |            |
|  |                 |  cross- |                  |            |
|  | Session State   |   ref   | Project Context  |            |
|  | Progress Track  |         | Relationships    |            |
|  | Decision Queue  |         | Boundaries       |            |
|  +--------+--------+         +--------+---------+            |
|           |                           |                      |
|           +-----------+---------------+                      |
|                       |                                      |
|           +-----------+-----------+                          |
|           |   Shared Foundation   |                          |
|           |   Unified media types |                          |
|           +-----------------------+                          |
|                                                               |
+---------------------------------------------------------------+
----

[cols="2,3,3"]
|===
| 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*
| `application/vnd.state+a2ml`
| `application/vnd.ecosystem+a2ml`
|===

See link:spec/family/SCM-FAMILY.adoc[SCM-FAMILY.adoc] for the complete family specification.

== Why ECOSYSTEM.a2ml?

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.

=== Use Cases

* **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)

== Quick Start

=== 1. Create an ECOSYSTEM.a2ml file

Place in your repository root:

[source,toml]
----
# SPDX-License-Identifier: MPL-2.0
# 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"
----

=== 2. Add Related Projects

[source,toml]
----
[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"
----

=== 3. Integrate with STATE.a2ml (Optional)

Reference your ECOSYSTEM.a2ml from STATE.a2ml for complete context:

[source,toml]
----
# In your STATE.a2ml file
[state.metadata]
version = "2.0"
ecosystem-ref = "./ECOSYSTEM.a2ml"
----

=== 4. Validate (Optional)

Validate against the unified family schema:

[source,bash]
----
# Using a hypothetical a2ml-to-json tool
a2ml-to-json ECOSYSTEM.a2ml | jsonschema -i - spec/family/a2ml-family.schema.json
----

== Specification

=== Format

* **Syntax:** TOML-like key-value (A2ML)
* **Encoding:** UTF-8
* **Media Type:** `application/vnd.ecosystem+a2ml`
* **File Extension:** `.a2ml` (conventionally `ECOSYSTEM.a2ml`)

=== Required Fields

[cols="2,4"]
|===
| Field | Description

| `version`
| Semantic version of document content

| `name`
| Canonical project name

| `type`
| Project category (library, application, service, etc.)

| `purpose`
| Concise description (1-3 sentences)
|===

=== Optional Fields

[cols="2,4"]
|===
| Field | Description

| `family`
| A2ML family membership declaration

| `position-in-ecosystem`
| Where this project fits in the broader ecosystem

| `related-projects`
| List of related projects with typed relationships

| `what-this-is`
| Detailed explanation of capabilities

| `what-this-is-not`
| Explicit boundaries and non-goals

| `specification`
| Technical metadata (for spec documents)

| `standards-track`
| Standardisation status and roadmap

| `future-integration`
| Planned integrations
|===

=== Relationship Types

[cols="2,4"]
|===
| Type | Meaning

| `consumer`
| Related project uses this project

| `producer`
| This project uses related project

| `sibling`
| Same organisation or ecosystem

| `sibling-standard`
| Related specification (e.g., STATE.a2ml)

| `complementary`
| Works alongside this project

| `alternative`
| Competing or alternative solution

| `inspiration`
| Design influence

| `fork` / `upstream` / `downstream`
| Code lineage relationships

| `potential-consumer`
| May use in future

| `deprecated-by` / `deprecates`
| Succession relationships
|===

== Standards Track

ECOSYSTEM.a2ml is pursuing formal standardisation through the **IETF Informational RFC** track as part of a coordinated A2ML family submission.

=== Current Status

[cols="2,3,1"]
|===
| Deliverable | Location | Status

| Canonical specification
| `ECOSYSTEM.a2ml`
| 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-a2ml-00.txt`
| Complete

| A2ML Family spec
| `spec/family/SCM-FAMILY.adoc`
| Complete

| IANA considerations
| `spec/IANA-CONSIDERATIONS.adoc`
| Complete

| Standards roadmap
| `STANDARDS-ROADMAP.adoc`
| Complete
|===

=== Why IETF?

* 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 link:STANDARDS-ROADMAP.adoc[STANDARDS-ROADMAP.adoc] for the complete standardisation plan.

== Project Structure

[source]
----
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.0
----

== Related Projects

=== STATE.a2ml (Sibling Standard)

Session state persistence for AI conversation continuity.

* Repository: link:../state-a2ml/[state-a2ml]
* Relationship: `sibling-standard`
* Domain: Temporal context (sessions, progress, decisions)
* Integration: Cross-reference via `ecosystem-ref` in 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)

== Contributing

See link:CONTRIBUTING.md[CONTRIBUTING.md] for guidelines.

=== Priority Contributions

1. **Unified parser library** - Rust library handling both STATE.a2ml and ECOSYSTEM.a2ml
2. **Validation tools** - CLI validators using family schema
3. **Editor support** - Syntax highlighting, snippets, LSP
4. **Feedback** - Use the formats and report issues

== Licence

Palimpsest-MPL License v1.0 (PMPL-1.0) - see link:LICENSE[LICENSE]

== Contact

* Issues: https://github.com/hyperpolymath/standards/issues
* Discussions: https://github.com/hyperpolymath/standards/discussions
