OpenRPC Specification

Version 1.2.4

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in BCP 14RFC2119RFC8174 when, and only when, they appear in all capitals, as shown here.

In the following description, if a field is not explicitly REQUIRED or described with a MUST or SHALL, it can be considered OPTIONAL.

Introduction

The OpenRPC Specification defines a standard, programming language-agnostic interface description for JSON-RPC 2.0 APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenRPC, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenRPC Specification removes guesswork in calling a service.

Use cases for machine-readable JSON-RPC API definition documents include, but are not limited to:

interactive documentation

code generation for documentation

clients

servers

automation of test cases.

OpenRPC documents describe a JSON-RPC APIs services and are represented in JSON format. These documents may either be produced and served statically or be generated dynamically from an application.

The OpenRPC Specification does not require rewriting existing JSON-RPC APIs. It does not require binding any software to a service — the service being described may not even be owned by the creator of its description. It does, however, require the capabilities of the service be described in the structure of the OpenRPC Specification. Not all services can be described by OpenRPC — this specification is not intended to cover REST APIs - It is exclusively for APIs which adhere to the JSON-RPC 2.0 spec. The OpenRPC Specification does not mandate a specific development process such as design-first or code-first. It does facilitate either technique by establishing clear interactions with a JSON-RPC API.

Definitions

OpenRPC Document

A document (or set of documents) that defines or describes an API. An OpenRPC document uses and conforms to the OpenRPC Specification.

Patterned Field

A field (key value pair) where the key name is supplied by the user, and the value is defined by the specification for the patterned field. The Field Pattern is a Regular expression.

Official OpenRPC Tooling

Tooling that is built, maintained and documented by the OpenRPC organization. It is meant to be used as a functional reference implementation of the Specification. Users of the OpenRPC Specification are encouraged to create versions of the tooling as their own organization/projects.

Versions

The major.minor portion of the semver (for example 1.0.x) SHALL designate the OpenRPC feature set. Typically, .patch versions address errors in this document, not the feature set. Tooling which supports OpenRPC 1.0.0 SHOULD be compatible with all OpenRPC 1.0.x versions. The patch version SHOULD NOT be considered by tooling, making no distinction between 1.0.0 and 1.0.1 for example.

Subsequent minor version releases of the OpenRPC Specification (incrementing the minor version number) SHOULD NOT interfere with tooling developed to a lower minor version and same major version. Thus a hypothetical 1.1.0 specification SHOULD be usable with tooling designed for 1.0.0.

An OpenRPC document compatible with OpenRPC 1.0.0 contains a required openrpc field which designates the semantic version of the OpenRPC that it uses.

Format

An OpenRPC document that conforms to the OpenRPC Specification is itself a JSON object, which must be represented in JSON format. Due to the nature of JSON-RPC APIs using JSON formats, strictly use JSON only as described here. If you wish to use any other format than JSON, it should be converted outside of any OpenRPC tooling.

It is RECOMMENDED that the OpenRPC document be named: openrpc.json. Tooling that requires an OpenRPC document as input MAY assume the default document location to be ./openrpc.json, where the ./ represents the current working directory.

All field names in the specification are case sensitive. CamelCase SHOULD be used for all key names.
This includes all fields that are used as keys in a map, except where explicitly noted that keys are case insensitive.

Rich Text Formatting

Throughout the specification description fields are noted as supporting Github markdown formatting.
Where OpenRPC tooling renders rich text it MUST support, at a minimum, markdown syntax as described by GitHub Flavored Markdown. Tooling MAY choose to ignore some GitHub Flavored Markdown features to address security concerns.

Service Discovery Method

JSON-RPC APIs can support the OpenRPC specification by implementing a service discovery method that will return the OpenRPC schema for the JSON-RPC API. The method MUST be named rpc.discover. The rpc. prefix is a reserved method prefix for JSON-RPC 2.0 specification system extensions. Below is the OpenRPC specification for the service discovery method:

{"methods":[{"name":"rpc.discover","description":"Returns an OpenRPC schema as a description of this service","result":{"name":"OpenRPC Schema","schema":{"$ref":"https://raw.githubusercontent.com/open-rpc/meta-schema/master/schema.json"}}}]}

Examples

Example OpenRPC documents can be found in the OpenRPC Examples Repository. There SHOULD be an example that uses every concept of the spec. These examples are to be used as the basis of testing for all the Official OpenRPC tooling.

Meta JSON Schema

Validating an OpenRPC document can be accomplished using the OpenRPC MetaSchema. The OpenRPC MetaSchema is based on the Draft 07 JSON Schema, and may be used as a JSON meta-schema for various tooling use. Each field in the Specification MUST be included in the OpenRPC MetaSchema, including all constraints that are possible to model with Draft 07 JSON Schema.

OpenRPC Object

This is the root object of the OpenRPC document. The contents of this object represent a whole OpenRPC document. How this object is constructed or stored is outside the scope of the OpenRPC Specification.

An array of Server Objects, which provide connectivity information to a target server. If the servers property is not provided, or is an empty array, the default value would be a Server Object with a url value of localhost.

Server Object

REQUIRED. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the OpenRPC document is being served. Server Variables are passed into the Runtime Expression to produce a server URL.

Server Variable Object

An enumeration of string values to be used if the substitution options are from a limited set.

default

string

REQUIRED. The default value to use for substitution, which SHALL be sent if an alternate value is not supplied. Note this behavior is different than the Schema Object’s treatment of default values, because in those cases parameter values are optional.

REQUIRED. A list of parameters that are applicable for this method. The list MUST NOT include duplicated parameters and therefore require name to be unique. The list can use the Reference Object to link to parameters that are defined by the Content Descriptor Object. It may also nest the content descriptor or reference object inside of a OneOf Object. All optional params (content descriptor objects with “required”: false) MUST be positioned after all required params in the list.

Schema Object

The Schema Object allows the definition of input and output data types.
The Schema Objects MUST follow the specifications outline in the JSON Schema Specification 7
Alternatively, any time a Schema Object can be used, a Reference Object can be used in its place. This allows referencing definitions instead of defining them inline.

Embedded literal example. The value field and externalValue field are mutually exclusive. To represent examples of media types that cannot naturally represented in JSON, use a string value to contain the example, escaping where necessary.

externalValue

string

A URL that points to the literal example. This provides the capability to reference examples that cannot easily be included in JSON documents. The value field and externalValue field are mutually exclusive.

In all cases, the example value is expected to be compatible with the type schema of its associated value. Tooling implementations MAY choose to validate compatibility automatically, and reject the example value(s) if incompatible.

Link Object

The Link object represents a possible design-time link for a result.
The presence of a link does not guarantee the caller’s ability to successfully invoke it, rather it provides a known relationship and traversal mechanism between results and other methods.

Unlike dynamic links (i.e. links provided in the result payload), the OpenRPC linking mechanism does not require link information in the runtime result.

For computing links, and providing instructions to execute them, a runtime expression is used for accessing values in an method and using them as parameters while invoking the linked method.

The name of an existing, resolvable OpenRPC method, as defined with a unique method. This field MUST resolve to a unique Method Object. As opposed to Open Api, Relative method values ARE NOT permitted.

A map representing parameters to pass to a method as specified with method. The key is the parameter name to be used, whereas the value can be a constant or a runtime expression to be evaluated and passed to the linked method.

Runtime Expression

Runtime expressions allow the user to define an expression which will evaluate to a string once the desired value(s) are known. They are used when the desired value of a link or server can only be constructed at run time.
This mechanism is used by Link Objects and Server Variables.

Error Object

REQUIRED. A Number that indicates the error type that occurred. This MUST be an integer. The error codes from and including -32768 to -32000 are reserved for pre-defined errors. These pre-defined errors SHOULD be assumed to be returned from any JSON-RPC api.

message

string

REQUIRED. A String providing a short description of the error. The message SHOULD be limited to a concise single sentence.

data

any

A Primitive or Structured value that contains additional information about the error. This may be omitted. The value of this member is defined by the Server (e.g. detailed error information, nested errors etc.).

Components Object

Holds a set of reusable objects for different aspects of the OpenRPC.
All objects defined within the components object will have no effect on the API unless they are explicitly referenced from properties outside the components object.

Reference Object

A simple object to allow referencing other components in the specification, internally and externally.

The Reference Object is defined by JSON Schema and follows the same structure, behavior and rules.

Field Name

Type

Description

$ref

string

REQUIRED. The reference string.

This object cannot be extended with additional properties and any properties added SHALL be ignored.

oneOf Object

A simple object allowing for conditional content descriptors. It MUST only be used in place of a content descriptor. It specifies that the content descriptor in question must match one of the listed content descriptors. This allows you to define content descriptors more granularly, without having to rely so heavily on json schemas.

The oneOf Object is defined by JSON Schema and follows the same structure, behavior and rules.