Specification overview

A Topo Project is a containerized sample project for Arm-based Linux systems. At minimum, it is a directory containing a compose.yaml, Dockerfiles, and source code, with an x-topo metadata block that describes what the Project does, what hardware features it requires, and what parameters a user can configure.

This specification defines the x-topo extension. It was developed for use with Topo CLI, but this is an open spec and any tool can read and act on x-topo metadata to discover, validate, and deploy Projects.

Not sure what these terms mean? Topo's glossary defines many of its core concepts.

How It Works

A Project's compose.yaml is a standard Compose file with an x-topo block at the root:

services:
  app:
    platform: linux/arm64
    build:
      context: .
      args:
        GREETING: "Hello, World"

x-topo:
  name: "hello-world"
  description: "A simple greeting app for Arm"
  features: ["NEON"]
  parameters:
    GREETING:
      description: "Message shown by the app"
      required: true
      example: "Hello from Arm"

Because this is valid Compose, any Project can be run with plain docker compose. The x-topo block is what allows tools like Topo to add interactive configuration, parameter validation, and target feature matching on top.

Specification

• Human-readable spec:
  • Authoring Topo Projects
  • Project Configuration
  • Schema Compliance
  • Build Optimization
  • Authoring Best Practices
• Machine-readable schema:
  • schema/topo-project-specification.json

Discover Topo Projects

A curated project catalog can be found either via:

• the topo projects command or
• the published Topo Project Catalog.

We welcome any contributors who wish to add their own Project to the project catalog to submit a Pull Request as indicated below.

Propose Your Project to Topo

If you want your Project to be added to the project catalog:

1. Review the Authoring Best Practices.
2. Review the catalog's Project Acceptance Criteria.
3. Validate Schema Compliance of your proposed Project.
4. Open a Pull Request in the Topo Project Catalog repository to update the catalog sources.

Validate Schema Compliance

The machine-readable schema to check any Project against is provided as a JSON schema and is therefore compatible with any supported tooling.

For validation workflows, see:

• Validating Schema Compliance in Your Editor
• Validating Schema Compliance using CLI

Versioning

This format follows Compose-style evolution and does not require strict schema-version pinning by implementations.

Implementations should follow Compose guidance for optional attributes.

Metadata
Status	Work in progress
Created	2025-11-10