OpenRPC Specification¶

Service description format for JSON-RPC protocol.

OpenRPC Object¶

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

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=None, terms_of_service=None, contact=None, license=None)¶

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=None, url=None, email=None)¶

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=None)¶

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=None, description=None, variables=None)¶

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=None, description=None)¶

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=None, summary=None, description=None, external_docs=None, params=<factory>, result=None, deprecated=None, servers=None, errors=None, links=None, param_structure=None, examples=None)¶

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 ExamplePairing objects where each example includes a valid params-to-result ContentDescriptor pairing.

property json¶: Returns the Method schema.

Content Descriptor Object¶

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

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=<not given>, *values, 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=None, description=None, params=<factory>, result=None)¶

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=None, summary=None, description=None, value=Undefined, external_value=None)¶

The object that defines an example that is intended to match the schema of a given 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.

Link Object¶

class jsonrpc.openrpc.Link(*, name, summary=None, description=None, method=None, params=None, server=None)¶

The Link object represents a possible design-time link for a result.

Parameters:

name (str) – Cannonical name of the link.
summary (str) – Short description for the link.
description (str) – A description of the link.
method (str) – The name of an existing OpenRPC method.
params (dict[str, Any]) – A dict object representing parameters to pass to a method as specified with method.
server (Server) – A Server object to be used by the target method.

property json¶: Returns the Link 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=None, schemas=None, examples=None, links=None, errors=None, example_pairing_objects=None, tags=None)¶

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

Parameters:

content_descriptors (dict[str, ContentDescriptor]) – An object to hold reusable ContentDescriptor objects.
schemas (dict[str, Any]) – An object to hold reusable schema objects.
examples (dict[str, Example]) – An object to hold reusable Example objects.
links (dict[str, Link]) – An object to hold reusable Link objects.
errors (dict[str, Error]) – An object to hold reusable Error objects.
example_pairing_objects (dict[str, ExamplePairing]) – An object to hold reusable ExamplePairing objects.
tags (dict[str, Tag]) – An object to hold reusable Tag objects.

property json¶: Returns the Components schema.

Tag Object¶

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

Adds metadata to a single tag that is used by the 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=None)¶

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.

Undefined Type Object¶

final class jsonrpc.openrpc.UndefinedType¶: Sentinel to indicate the lack of a value when None is ambiguous.