A registry of machine-readable specifications -- library APIs, UI flows, protocols, data formats, and more -- that AI agents use to generate native implementations.
Traditional package registries distribute executable code. This creates:
- Supply chain attacks — malicious code in dependencies
- Dependency hell — transitive dependency conflicts and version drift
- Language lock-in — a Python library doesn't help your Rust project
- Bloat — you need one function, you get 10,000 lines of code
Canra distributes specifications, not code. When your project needs JSON parsing or an auth flow, your AI agent:
- Fetches the spec from this registry
- Reads the structure, requirements, and test vectors
- Generates a native implementation in your project's language and framework
- Runs the spec's test vectors to verify correctness
The result is first-party code -- auditable, minimal, and with zero third-party dependencies.
Agents fetch specs by name over HTTP -- no git clone needed, no catalog to download.
Step 1: Fetch spec metadata
GET /api/specs/{name}
Returns metadata (tags, references, dependencies, test vector counts) for the latest version. Returns 404 if the spec doesn't exist.
Step 2: Check available versions (optional)
GET /api/specs/{name}/versions
Returns a list of all published versions for a spec.
Step 3: Fetch the spec content
GET /specs/{name}/{name}.spec.md
The spec file contains everything needed to generate an implementation: structure, requirements, and test vectors.
Step 4: Generate and test
- Read the spec's sections (screens, types, functions, rules -- varies by spec type)
- Read the requirements (MUST/SHOULD/MAY) for acceptance criteria
- Generate an implementation in the target language and framework
- Generate tests from the test vectors
- Run tests to verify correctness
- Record the spec name and version in a
canra.lockfile for reproducibility
Browse the specs/ directory. Each spec lives in specs/{name}/{name}.spec.md.
| Spec | Type | Tags | Standard |
|---|---|---|---|
| json | library | serialization, data-interchange | RFC 8259 |
| uuid | library | identifiers, random, time-based | RFC 9562 |
| email-password-auth | ui-flow | auth, security, forms | OWASP, NIST 800-63B |
Each spec is a .spec.md file with TOML front-matter (+++ delimiters) and a Markdown body. Specs can use any H2 sections in any order -- there is no rigid template. Each spec uses whatever structure best communicates its design.
Library specs typically include: Overview, Types, Functions, Behavioral Contracts, Test Vectors, Edge Cases, Implementation Notes, References.
UI flow specs might use: Overview, Screens, Validation Rules, Requirements, Test Vectors, Edge Cases, Implementation Notes, References.
All specs include test vectors (input/output pairs in JSONL format) for verification.
See CONTRIBUTING.md for the full format specification.
Specs use simple incrementing integer versions. Each published version is immutable -- once published, its content cannot change.
What triggers a version bump: Any change to a spec's content (structure, requirements, test vectors, clarifications, etc.) increments the version by 1.
Accessing old versions: The /api/specs/{name}/versions endpoint lists all published versions with their content hashes and download URLs.
When an AI agent generates code from a spec, it should record the spec version used in a canra.lock file in the project root. This enables reproducible builds and spec update tracking.
# canra.lock — auto-generated, do not edit manually
[specs.json]
version = "2"
generated = "2026-02-17"
[specs.uuid]
version = "2"
generated = "2026-02-17"The lockfile allows agents to:
- Detect when a newer spec version is available
- Re-generate code from the exact same spec version
- Audit which specs were used in a project
- A Bun HTTP server provides a JSON API for publishing, searching, and fetching specs
- PostgreSQL stores all spec metadata and powers full-text search (
pg_trgm+ a generatedtsvector) - DigitalOcean Spaces stores versioned spec files as immutable objects
- Agents fetch specs by name over HTTP -- no git clone needed
- Sample specs in the
specs/directory are synced to the database on deploy
Specs are community-sourced and maintained. See CONTRIBUTING.md for how to propose and write specs.
MIT — see LICENSE.