MSR JSON — Specification

The normative artifacts of the MSR JSON open metadata protocol: the JSON Schemas, the reference manifests and the RFCs, ratified and in draft.

This repository is the single source of truth. https://msrjson.org serves these files and consumes this repository directly; it never keeps its own copy. If the two ever disagree, this repository is right.

Current version: MSR JSON 2.1.0, canonical schema https://msrjson.org/schemas/msr-2.1.json. It is the schema's $id, what a new manifest puts in $schema, and the address the file is served from.

MSR JSON 2.0 stays valid and served at https://msrjson.org/schemas/msr-2.0.json; a 2.0 manifest does not need to change. Manifests published before 2026-09-19 name 2.0 as https://msr-standard.org/schemas/msr-2.0.json; that identifier stays valid as an alias, and registries resolve it to the msrjson.org URL.

What MSR JSON is

A publisher describes their software once, in a manifest hosted on their own domain:

https://your-domain.example/.well-known/msr.json

Registries, package managers and AI discovery engines read that manifest instead of scraping a product page. There is no central registry to apply to, no gatekeeper and no vendor who owns the format.

Contents

Path	What it is
schemas/msr-2.1.json	The current schema, MSR JSON 2.1.0 (JSON Schema Draft 2020-12), strict: unknown properties are rejected
schemas/msr-2.0.json	MSR JSON 2.0.0, still valid
schemas/msr-1.1.json	Legacy v1.1, kept for the PAD XML migration bridge
schemas/msr-2.1-draft.json	Superseded v2.1 draft, identical to msr-2.1.json apart from $id; kept so draft manifests keep resolving
examples/*.json	Six reference manifests, one per entity type, each validating with zero errors
rfc/rfc-0001..0003.html	The ratified RFCs of MSR JSON 2.0
rfc/rfc-0006.html	Ratified in 2.1: geographic and language availability
rfc/rfc-0007.html	Working draft: registry conformance and ingestion
rfc/rfc-0008.html	Ratified in 2.1: media, distribution, execution requirements and Push-Ping
rfc/rfc-0009.html	Ratified in 2.1: entity.category and entity.subcategories
taxonomy/categories.json	The MSR category taxonomy (RFC 0009), versioned independently of the protocol
tests/	The conformance suite below

The MSR JSON repositories

Repository	What it is	Status
specification	This repository — the source of truth	Published
msr-validator	Reference validator library, in Python	Not yet released
msr-cli	Reference command-line tool, the msr command	Not yet released

Dependencies point one way only: msr-cli uses msr-validator, which bundles the schema from a pinned release of this repository. This repository depends on nothing. No other repository may keep its own copy of the schema.

Generating a manifest with an AI agent

AGENTS.md is written for AI agents of any model asked to create an msr.json for a project: what the protocol is, the constant protocol block, the procedure, the values that must never be invented, and a tested validation command.

Verify the standard yourself

Nothing here is taken on trust. The suite checks that the canonical schema is well-formed Draft 2020-12, that its $id is the canonical URL, that all six examples validate with zero errors, and that manifests which should be rejected are in fact rejected:

pip install -r requirements-test.txt
python -m pytest tests -q

No container, no network, no project-specific tooling. It runs the same way in CI on every push and pull request.

To validate a manifest of your own:

pip install check-jsonschema
check-jsonschema \
  --schemafile https://msrjson.org/schemas/msr-2.1.json \
  .well-known/msr.json

What MSR JSON 2.1 adds

Every field below is optional, and every object stays closed (additionalProperties: false):

• capabilities.availability — regions, countries, languages, currencies and data residency (RFC 0006). 2.1 also requires the keys of entity.descriptions to be BCP 47 language tags.
• entity.media, distribution.package_managers, distribution.app_stores, capabilities.requirements and telemetry.ping_endpoints (RFC 0008). Media and ping URLs must use https://.
• entity.category and entity.subcategories, slugs of taxonomy/categories.json (RFC 0009).

A manifest that uses none of them validates against both 2.0 and 2.1. The source versions of msr-validator and msr-cli are not released and still default to the 2.0 schema; pass msr-2.1.json explicitly.

Changelog

Every change to the specification and to this repository is recorded in CHANGELOG.md, with its effect on what validates.

Changing the protocol

Schema changes do not land as pull requests against schemas/. They go through the RFC process: write the proposal in rfc/, following the shape of the ratified ones, with the schema diff and the security considerations stated explicitly. Two independent implementations must demonstrate interoperability before a 30-day call for consensus.

A change that alters what validates is a MAJOR version under the compatibility policy. Additive, backwards-compatible changes are MINOR. See https://msrjson.org/governance/.

Typos, broken examples and documentation corrections are ordinary pull requests and are welcome as such.

Author

MSR JSON was created and authored by Antonio Santos — Esplanada, Bahia, Brazil — author of the Craft Engine framework. Contact: [email protected]. Full statement in AUTHORS.

Attribution to the author is a condition of the CC-BY-4.0 license the specification is published under. Authorship and stewardship are deliberately separate: the protocol is authored by one person and governed in the open, through the RFC process and the neutrality charter.

Licensing

Dual-licensed, deliberately:

• Specification text, schemas, examples, RFCs — CC-BY-4.0. Free to implement, quote and translate, with attribution. It cannot be privatized, patented or encumbered by fees.
• Tests and CI — MIT.

The scope of each license is stated in NOTICE.

Implementing MSR JSON requires no permission, no fee and no registration.