Versioning

Versions follow the semver.org rules.

Semantic versioning (MAJOR.MINOR.PATCH). The version string appears at the manifest root, on each service, and on each capability; capabilities may carry different versions in one manifest.

Change Bump
Breaking — field removal, type change, semantic change MAJOR
Additive — new optional fields, new capabilities MINOR
Docs, clarifications, non-breaking fixes PATCH

Consumers must ignore unknown fields (forward compatibility). All BEST identifiers use reverse-domain notation; io.best.* is reserved for the specification.

Release Version

The release version is the git tag — v0.9.21, v1.0.0, etc. This is the version implementers and consumers reference in documentation, dependency declarations, and compatibility checks.

The version string (without the v prefix) appears in:

  • The /.well-known/best manifest root — best.version
  • Each service definition — services["io.best.*"].version
  • Each capability definition — capabilities[*].version
{
  "best": {
    "version": "0.9.21",
    "services": {
      "io.best.agents": { "version": "0.9.21", "..." : "..." }
    },
    "capabilities": [
      { "name": "io.best.agents.commands", "version": "0.9.21", "..." : "..." }
    ]
  }
}

On a MAJOR bump, consumers should review the changelog.

Namespace Convention

The specification's identifiers take the form io.best.{service}.{capability}, such as io.best.agents.commands. Implementation-specific capabilities use their own namespace (e.g. com.example.custom-capability).

spec/v0.9.21