Ribosome Schema

The manifest & lockfile standard for ribosome, the MCP package manager. Normative JSON Schemas for the ribosome.json project manifest and the ribosome.lock.json output, a conformance corpus, and a TypeScript binding.

CI npm npm downloads schema: live License: Apache 2.0 Status: alpha

What this is

Think of the npm ecosystem: npm is the tool, but package.json and the lockfile format are a separate, stable standard that anything can read and write. This repo is that standard for MCP dependency management:

• ribosome is the package manager (the tool) — MPL-2.0.
• ribosome-schema (this repo) is the format it reads — Apache-2.0, so you can implement it in any product, open or closed, with no copyleft obligation.

It holds the standard, and only the standard — no resolver, no runtime, no orchestration logic. ribosome is the reference consumer, but the standard stands on its own.

What's here

schema/v1/            the standard — manifest.schema.json, lockfile.schema.json
vendor/               the pinned, vendored MCP server.json schema (MIT, upstream)
conformance/          valid/ + invalid/ fixtures — the executable specification
bindings/typescript/  generated types + validation + version pins (npm package)

Use it

In any language, without npm. JSON Schema is language-agnostic by design. Point any validator (Python jsonschema, Go gojsonschema, Rust jsonschema-rs, …) at the canonical, live $id:

https://schema.ribosome.medullaflow.org/v1/manifest.schema.json
https://schema.ribosome.medullaflow.org/v1/lockfile.schema.json

Hosted on a GitHub Pages custom domain, published on every push to main by publish-pages.yml — which deploys only the *.schema.json files plus schema/CNAME, nothing else in this repo.

From TypeScript/JavaScript, with generated types and an offline ajv-based validator:

npm install @medullaflow/ribosome-schema

import { validateManifest, checkManifest, type RibosomeManifest } from "@medullaflow/ribosome-schema";

const manifest = validateManifest(JSON.parse(raw)); // throws SchemaValidationError, listing every failure
const { valid, errors } = checkManifest(data);      // non-throwing variant

Status

Alpha. The schemas, conformance corpus, and TypeScript binding are real and tested; the schema is hosted live at its canonical $id (schema.ribosome.medullaflow.org) and published to npm as @medullaflow/ribosome-schema; SPEC.md pins down the interface's compatibility rules and the semantics this schema deliberately leaves opaque. What's next is in ROADMAP.md.

Versioning

Four independent version numbers exist here. Each has exactly one hand-authored source; everything else is generated or checked against it — never a second hand-typed copy.

Manifest and lockfile are versioned together, as one schema family — the lockfile is "the resolved output of a manifest," so they always move as a couple. Both schema/v1/*.schema.json must declare the identical schemaVersion const; scripts/gen-types.js refuses to run if they diverge.

What requires a schemaVersion bump: removing/renaming a field, changing a field's type or making an optional field required — anything that would make a previously-valid document invalid. What doesn't: adding an optional field, loosening a constraint, fixing a description.

Development

bun install          # root tooling deps (codegen)
bun run spec:types   # regenerate bindings/typescript/src/types.ts from schema/v1/
bun run test         # build the TS binding + run the conformance corpus against it
bun run vendor:check # verify the vendored server.json against its pin (local + upstream)

Toolchain is bun, not Node — for consistency with ribosome's own toolchain (see its docs/ARCHITECTURE.md D14). One deliberate exception: publish-npm.yml's final publish step stays on the npm CLI, since bun publish doesn't yet support npm's OIDC trusted publishing.

Licensing

Apache-2.0 — see LICENSE and NOTICE. Per-file detail (the one vendored exception) is machine-readable via REUSE (REUSE.toml); full texts in LICENSES/.

Security

See SECURITY.md for how to report a vulnerability privately.

Contributing

See CONTRIBUTING.md — what goes where (schema vs. binding), the version-bump procedure, DCO sign-off, and how to add yourself to AUTHORS.

Attribution

Principal authorship and copyright: AUTHORS; primary author Matteo Lacchio — @ookmash. Full contributor list: the Contributors graph.