MSR JSON Protocol Specification

1. Abstract & Status

For over two decades, the Association of Shareware Professionals maintained the PAD (Portable Application Description) XML standard. PAD enabled developers to publish software once and have download portals (such as Tucows, Download.com, and Softpedia) ingest updates automatically without proprietary APIs.

However, legacy XML architectures present fundamental constraints in the modern software landscape: verbose CDATA sections, XXE vulnerabilities, lack of first-class internationalization, floating-point currencies, and total inability to represent SaaS backends, Model Context Protocol (MCP) servers, or autonomous AI agents.

The MSR JSON (Metadata for Software Registry) protocol v2.0 solves these challenges while preserving the decentralized ethos: software publishers remain the sole source of truth by hosting their metadata on their own domain, discoverable over standardized HTTP endpoints (RFC 8615).

2. Conformance & Key Words

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC 2119] [RFC 8174] when, and only when, they appear in all capitals.

An implementation is non-conformant if it fails to satisfy one or more of the MUST or REQUIRED statements for the sections it claims to support. Every conformant MSR JSON manifest MUST be a valid JSON document conforming to RFC 8259 and MUST validate without errors against the canonical JSON Schema (Draft 2020-12).

3. Core Architectural Principles

4. Document Anatomy

An MSR JSON document consists of five mandatory top-level objects and two optional objects:

{
  "$schema": "https://msr-standard.org/schemas/msr-2.0.json",
  "protocol": { ... },     // REQUIRED: Standard provenance and SemVer
  "entity": { ... },       // REQUIRED: Machine identity, FQDN, localized descriptions
  "capabilities": { ... }, // REQUIRED: Interfaces (MCP, OpenAPI), deployment, pricing
  "releases": { ... },     // REQUIRED: Latest version, changelog, and artifacts
  "trust": { ... },        // OPTIONAL: DNS-TXT proof, Ed25519 manifest signature
  "telemetry": { ... }     // OPTIONAL: Status page URL and push synchronization webhooks
}

4.1 Protocol Object (protocol)

Declares adherence to the specification and transparent provenance.

4.2 Entity Object (entity)

Describes the identity, categorization, publisher entity, and localized descriptions.

4.3 Capabilities Object (capabilities)

Declares deployment targets, functional interfaces (OpenAPI, MCP, gRPC), pricing, and ecosystem integrations.

Not in 2.0: where a product may be bought and used, its interface and support languages, its billing currencies and where customer data is stored are proposed in RFC 0006 as capabilities.availability. It is a working draft, present only in msr-2.1-draft.json; a 2.0 manifest that carries it fails validation.

4.4 Releases Object (releases)

Details regarding active and historical distribution artifacts.

4.5 Trust Object (trust)

Cryptographic proof, domain ownership attestations, and security audits.

4.6 Telemetry Object (telemetry)

Availability endpoints and bi-directional event notifications.

5. Verification Standard

5.1 Domain Ownership Proof

Aggregators MUST NOT allow arbitrary third-party accounts to claim authority over external domains. Conformance requires one of two verification channels:

1. RFC 8615 Well-Known HTTP Proof: The manifest is fetched directly over HTTPS from https://<domain>/.well-known/msr.json using an SSRF-hardened HTTP client (strictly rejecting private/loopback IP blocks).
2. DNS-TXT Challenge: A DNS TXT record on _msr-challenge.<domain> containing the registry token.

5.2 Webhook Signature Verification

When registries send event notifications to telemetry.webhook.url, they MUST include two HTTP request headers:

• X-MSR-Timestamp: Integer Unix epoch timestamp.
• X-MSR-Signature: Hex-encoded HMAC-SHA256 signature calculated over timestamp + "." + raw_body.

import hmac, hashlib

def verify_msr_webhook(secret: bytes, timestamp: str, raw_body: bytes, header_sig: str) -> bool:
    signed_payload = f"{timestamp}.".encode("utf-8") + raw_body
    computed = "sha256=" + hmac.new(secret, signed_payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(computed, header_sig)

6. Compatibility & Migration Guides

MSR JSON v2.0 is designed as an upgrade path for existing metadata standards:

• Migrating from PAD XML: Use the official CLI utility msr convert --from-pad <file.xml> to automatically transform legacy XML fields into normalized MSR v2.0 structures. Floating-point prices are automatically converted to minor currency units.
• Migrating from MSR v1.x: Top-level software and vendor blocks are consolidated into entity, and pad_version is replaced by protocol.version.
• OpenAPI 3.1 Linkage: Simply declare your existing OpenAPI specification inside capabilities.interfaces.openapi to enable automatic API indexing.

7. Developer Examples

Review complete, validated manifests for various deployment archetypes:

• SaaS Cloud Observability Platform
• REST / gRPC Vector Gateway API
• Model Context Protocol (MCP) Server
• Autonomous AI Security Agent
• Open Source Embedded Key-Value Engine
• Cross-Platform Desktop Graphics Studio

8. Specification Changelog