draft mandatory
This document defines the common language and core concepts used across all Open Ranking Enhancements.
All occurrences of MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY in this and all subsequent OREs MUST be interpreted as described in RFC 2119.
OREs, or Open Ranking Enhancements, are short documents that define a specific endpoint, feature, or protocol rule that an Open Ranking provider MUST or MAY implement.
Each ORE is identified by a number (e.g. ORE-00, ORE-01) or a letter (e.g. ORE-A, ORE-B). OREs are either mandatory or optional. Mandatory OREs MUST be implemented by all compliant providers. Optional OREs MAY be implemented and, if implemented, MUST be implemented within the bounds specified.
A provider is an HTTP server that implements one or more Open Ranking endpoints. Providers are free to optimize internally, in terms of indexing strategy, caching, and pipeline design, as long as they conform to the protocol surface defined by the OREs they support.
An algorithm is a provider-defined ranking or search strategy, identified by an opaque string. Algorithm identifiers MUST be lowercase and MUST use only alphanumeric characters, hyphens, and dots (e.g. pagerank-v1, social.follows). A provider MAY expose multiple algorithms for the same endpoint.
A pubkey is a Nostr public key encoded as a 64-character lowercase hex string. Providers and clients MUST use the hex encoding for pubkeys in all requests and responses. The npub bech32 encoding MUST NOT be used in the protocol.
All request bodies MUST be JSON. Clients MUST set the Content-Type: application/json header on requests that include a body.
All response bodies MUST be JSON. Providers MUST set the Content-Type: application/json header on all responses.
Providers MUST include the Access-Control-Allow-Origin: * header on all responses. Providers MUST also handle OPTIONS preflight requests on all endpoints, responding with 200 and the appropriate Access-Control-Allow-Headers and Access-Control-Allow-Methods headers.
When a request cannot be fulfilled, providers MUST respond with an appropriate HTTP error status code. Providers SHOULD include a human-readable description of the problem in the X-Reason response header.