draft mandatory
This document defines the capability document that every Open Ranking provider MUST expose. It allows clients to discover which endpoints and algorithms a provider supports.
The capability document is intentionally minimal, as it is designed for machine discovery. Clients need a stable, predictable structure to query providers programmatically. Allowing arbitrary provider-specific fields would break that predictability and make interoperability harder.
Concerns such as pricing, rate-limiting, and authentication are out of scope and MUST NOT appear in the capability document. Providers SHOULD advertise such information on their homepage or documentation instead.
GET /.well-known/open-ranking.json
Providers MUST serve the capability document at this well-known location. The response MUST have a Content-Type: application/json header and a 200 status code.
The capability document is a JSON object. Each key is a supported endpoint path (e.g. /reputation). Each value is a non-empty array of Algorithm Objects supported by that endpoint.
An Algorithm Object describes a single ranking or search strategy offered by a provider for a given endpoint.
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | yes | The algorithm identifier, as defined in ORE-00. |
pov |
boolean | no | If true, the algorithm is personalized and requires a pov pubkey in every request. If absent or false, the algorithm is global. |
description |
string | no | A short human-readable description of the algorithm. MAY be displayed to users. MUST be plain UTF-8 with no markup. |
name |
string | no | A human-readable display name for the algorithm. MAY be shown in place of id in client UIs. |
icon |
string | no | A URL pointing to an icon representing the algorithm. Clients MAY display this image alongside the algorithm name. |
learn_more |
string | no | A URI pointing to further information about the algorithm (e.g. a webpage, a Nostr event). Clients MAY surface this as a link alongside the description. |
Clients MUST ignore unknown fields on Algorithm Objects. This ensures clients remain functional as new OREs introduce additional fields.
Providers MUST NOT add fields to Algorithm Objects that are not defined in a ratified ORE.
{
"/stats/pubkeys": [
{
"id": "pagerank",
"name": "Global PageRank",
"description": "Global PageRank computed on the Nostr social graph. Very fast.",
"icon": "https://example.com/icons/pagerank.png",
"learn_more": "https://example.com/docs/pagerank"
},
{
"id": "personalized-pagerank",
"name": "Personalized PageRank",
"description": "Personalized PageRank, computed using the provided pov pubkey.",
"pov": true,
"icon": "https://example.com/icons/personalized-pagerank.png",
"learn_more": "https://example.com/docs/personalized-pagerank"
}
],
"/rank/pubkeys": [
{
"id": "wot-rank",
"name": "Web of Trust Rank",
"description": "Web of Trust Rank, computed using the provided pov pubkey.",
"pov": true,
"icon": "https://example.com/icons/wot-rank.png",
"learn_more": "https://example.com/docs/wot-rank"
}
]
}Clients MAY specify a preferred algorithm in a request. If no algorithm is specified, the provider MUST use the default algorithm for that endpoint, which is the first element in that endpoint's array. If the requested algorithm is not supported by the specific endpoint, the provider MUST respond with 422 Unprocessable Content.
Clients MUST specify a pov pubkey in the request if the specified algorithm requires it in the capability document.
Providers MUST respond with 422 Unprocessable Content if a request does not include a pov for an algorithm that requires one.
Clients MUST NOT send a pov to an algorithm that doesn't require it. If a pov is sent to a global algorithm, the provider MUST ignore it.
Providers SHOULD express algorithm variants as distinct named algorithms. This avoids the need for algorithm-specific parameters that break interoperability, as custom parameters require every client to understand its meaning, its valid range, and how to present it to the user.