Open Primitive

Open Primitive Protocol

v0.1.0

1 Overview

OPP defines how data providers make their data agent-consumable, verifiable, and discoverable. Three components: manifest, envelope, endpoint.

2 Manifest

Every OPP provider publishes a manifest at /.well-known/opp.json

Field Description
@context required Protocol namespace URL. string
name Human-readable name of this provider. string
description What this provider offers. string
version Provider version. string
protocolVersion OPP version this manifest conforms to. string
provider.name Organization or person operating this provider. string
provider.url Provider homepage. string (URL)
provider.contact Contact email or URL. string
provider.publicKey Ed25519 public key for response verification. string
domains[] Array of data domains this provider serves.
domains[].id Machine-readable domain identifier. string
domains[].name Human-readable domain name. string
domains[].source Upstream data source URL. string (URL)
domains[].entityTypes[] Types of entities queryable in this domain. string[]
domains[].freshness How often data is refreshed. string
domains[].license License governing this data. string
endpoints.base Base URL for all API endpoints. string (URL)
endpoints.query Query endpoint path template. string
discovery.openapi Path to OpenAPI spec. string
discovery.llms Path to LLM-readable description. string
discovery.mcpServer MCP server endpoint. string (URL)
discovery.agentCard A2A agent card endpoint. string (URL)
geographic.scope Geographic coverage. string
geographic.granularity Finest geographic resolution. string
authentication.type Auth type: none, apiKey, bearer. string
authentication.header Header name for auth token. string

3 Response Envelope

Every OPP response wraps data in a standard envelope.

{
  "domain": "string — which dataset",
  "source": "string — the data provider",
  "source_url": "string — upstream source URL",
  "freshness": "ISO 8601 — when data was last pulled",
  "data": "object — domain-specific payload",
  "confidence": {
    "completeness": "0-1 — percentage of expected fields present",
    "methodology": "string — how data was collected",
    "note": "string — data limitations"
  },
  "citations": {
    "statement": "string — pre-formatted citation agents can paste",
    "source_url": "string",
    "license": "string"
  },
  "version": {
    "data": "string — temporal version of the data",
    "schema": "string — schema version",
    "protocol": "string — OPP version"
  },
  "proof": {
    "type": "DataIntegrityProof",
    "cryptosuite": "eddsa-jcs-2022",
    "verificationMethod": "URL to public key",
    "proofValue": "base58 signature"
  }
}

4 Discovery

Agents discover OPP providers through three mechanisms:

/.well-known/opp.json

Any crawler can find it. Same convention as robots.txt or security.txt. Agents fetch this first.

MCP Server Cards

Agents using MCP discover tools through the server card referenced in the manifest's discovery.mcpServer field.

A2A Agent Cards

Agents using A2A discover skills through the agent card referenced in the manifest's discovery.agentCard field.

5 Verification

Responses are signed with Ed25519. Public key is in the manifest. Agents verify before trusting.

  1. Fetch /.well-known/opp.json and extract provider.publicKey
  2. Fetch data response and extract proof.proofValue
  3. Verify signature against public key
  4. Check source matches a known federal URL
  5. Check freshness is within acceptable range

6 Implement It

Any data provider can implement OPP in an afternoon.

  1. Create /.well-known/opp.json with your manifest
  2. Add envelope fields to your JSON responses
  3. Generate an Ed25519 key pair and sign responses
  4. Register with the Open Primitive registry (coming soon)