OpenRPC Specification

Service description format for JSON-RPC protocol.

OpenRPC Object

class jsonrpc.openrpc.OpenRPC(*, openrpc='1.3.2', info, servers=<factory>, methods=<factory>, components=Undefined, external_docs=Undefined)

This is the root object of the OpenRPC document.

Parameters:
  • openrpc (str) – The version string of OpenRPC.

  • info (Info) – Provides metadata about the API.

  • servers (list[Server]) – An array of servers, which provide connectivity information to a target server.

  • methods (list[Method]) – The available methods for the API.

  • components (Components) – An element to hold various schemas for the specification.

  • external_docs (ExternalDocumentation) – Additional external documentation.

property json

Returns the OpenRPC schema.

Info Object

class jsonrpc.openrpc.Info(*, title, version, description=Undefined, terms_of_service=Undefined, contact=Undefined, license=Undefined)

The object provides metadata about the API.

Parameters:
  • title (str) – The title of the application.

  • version (str) – The version of the OpenRPC document.

  • description (str) – A verbose description of the application.

  • terms_of_service (str) – A URL to the Terms of Service for the API.

  • contact (Contact) – The contact information for the API.

  • license (License) – The license information for the API.

property json

Returns the Info schema.

Contact Object

class jsonrpc.openrpc.Contact(*, name=Undefined, url=Undefined, email=Undefined)

Contact information for the API.

Parameters:
  • name (str) – The identifying name of the contact person/organization.

  • url (str) – The URL pointing to the contact information.

  • email (str) – The email address of the contact person/organization.

property json

Returns the Contact schema.

License Object

class jsonrpc.openrpc.License(*, name, url=Undefined)

License information for the API.

Parameters:
  • name (str) – The license name used for the API.

  • url (str) – A URL to the license used for the API.

property json

Returns the License schema.

Server Object

class jsonrpc.openrpc.Server(*, name, url, summary=Undefined, description=Undefined, variables=<factory>)

An object representing a Server.

Parameters:
  • name (str) – A name to be used as the cannonical name for the server.

  • url (str) – A URL to the target host.

  • summary (str) – A short summary of what the server is.

  • description (str) – An optional string describing the host designated by the URL.

  • variables (dict[str, ServerVariable]) – A dict between a variable name and its value.

property json

Returns the Server schema.

Server Variable Object

class jsonrpc.openrpc.ServerVariable(*, default, enum=<factory>, description=Undefined)

An object representing a Server Variable for server URL template substitution.

Parameters:
  • default (str) – The default value to use for substitution.

  • enum (list[str]) – An enumeration of string values to be used if the substitution options are from a limited set.

  • description (str) – An optional description for the server variable.

property json

Returns the Server Variable schema.

Method Object

class jsonrpc.openrpc.Method(*, name, tags=<factory>, summary=Undefined, description=Undefined, external_docs=Undefined, params=<factory>, result=Undefined, deprecated=False, servers=<factory>, errors=<factory>, links=<factory>, param_structure=ParamStructure.EITHER, examples=<factory>)

Describes the interface for the given method name.

Parameters:
  • name (str) – The cannonical name for the method.

  • tags (list[Tag]) – A list of tags for API documentation control.

  • summary (str) – A short summary of what the method does.

  • description (str) – A verbose explanation of the method behavior.

  • external_docs (ExternalDocumentation) – Additional external documentation for this method.

  • params (list[ContentDescriptor]) – A list of parameters that are applicable for this method.

  • result (ContentDescriptor) – The description of the result returned by the method.

  • deprecated (bool) – Declares this method to be deprecated.

  • servers (list[Server]) – An alternative servers array to service this method.

  • errors (list[Error]) – A list of custom application defined errors that may be returned.

  • links (list[Link]) – A list of possible links from this method call.

  • param_structure (ParamStructure) – The expected format of the parameters.

  • examples (list[ExamplePairing]) – Array of jsonrpc.openrpc.ExamplePairing objects where each example includes a valid params-to-result jsonrpc.openrpc.ContentDescriptor pairing.

property json

Returns the Method schema.

Content Descriptor Object

class jsonrpc.openrpc.ContentDescriptor(*, name, summary=Undefined, description=Undefined, required=False, schema=<factory>, deprecated=False)

Content Descriptors are objects that do just as they suggest – describe content. They are reusable ways of describing either parameters or result.

Parameters:
  • name (str) – Name of the content that is being described.

  • summary (str) – A short summary of the content that is being described.

  • description (str) – A verbose explanation of the content descriptor behavior.

  • required (bool) – Determines if the content is a required field.

  • schema (dict[str, Any]) – Schema that describes the content.

  • deprecated (bool) – Specifies that the content is deprecated and should be transitioned out of usage.

property json

Returns the Content Descriptor schema.

Param Structure Object

final class jsonrpc.openrpc.ParamStructure(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Param Structure is the expected format of the parameters.

BY_NAME = 'by-name'

Parameters must contains named arguments as a by-name object.

BY_POSITION = 'by-position'

Parameters must contains positional arguments as a by-position array.

EITHER = 'either'

Parameters can be either named arguments or positional arguments.

Example Pairing Object

class jsonrpc.openrpc.ExamplePairing(*, name, summary=Undefined, description=Undefined, params=<factory>, result=Undefined)

The Example Pairing object consists of a set of example params and result.

Parameters:
  • name (str) – Name for the example pairing.

  • summary (str) – Short description for the example pairing.

  • description (str) – A verbose explanation of the example pairing.

  • params (list[Example]) – Example parameters.

  • result (Example) – Example result.

property json

Returns the Example Pairing schema.

Example Object

class jsonrpc.openrpc.Example(*, name=Undefined, summary=Undefined, description=Undefined, value=Undefined, external_value=Undefined)

The object that defines an example that is intended to match the schema of a given jsonrpc.openrpc.ContentDescriptor. The value field and external_value field are mutually exclusive.

Parameters:
  • name (str) – Cannonical name of the example.

  • summary (str) – Short description for the example.

  • description (str) – A verbose explanation of the example.

  • value (Any) – Embedded literal example.

  • external_value (str) – A URL that points to the literal example.

Raises:

TypeError – If value and external_value fields are specified both.

property json

Returns the Example schema.

Error Object

class jsonrpc.openrpc.Error(*, code, message, data=Undefined)

Defines an application level error.

Parameters:
  • code (int) – An int object that indicates the error type that occurred.

  • message (str) – A str object providing a short description of the error.

  • data (Any) – A primitive or structured value that contains additional information about the error.

property json

Returns the Error schema.

Components Object

class jsonrpc.openrpc.Components(*, content_descriptors=<factory>, schemas=<factory>, examples=<factory>, links=<factory>, errors=<factory>, example_pairing_objects=<factory>, tags=<factory>)

Holds a set of reusable objects for different aspects of the OpenRPC.

Parameters:
property json

Returns the Components schema.

Tag Object

class jsonrpc.openrpc.Tag(*, name, summary=Undefined, description=Undefined, external_docs=Undefined)

Adds metadata to a single tag that is used by the jsonrpc.openrpc.Method object.

Parameters:
  • name (str) – The name of the tag.

  • summary (str) – A short summary of the tag.

  • description (str) – A verbose explanation for the tag.

  • external_docs (ExternalDocumentation) – Additional external documentation for this tag.

property json

Returns the Tag schema.

External Documentation Object

class jsonrpc.openrpc.ExternalDocumentation(*, url, description=Undefined)

Allows referencing an external resource for extended documentation.

Parameters:
  • url (str) – The URL for the target documentation.

  • description (str) – A verbose explanation of the target documentation.

property json

Returns the External Documentation schema.