JSON+RPC 1.0 Specification

Date: 2024-08-06

Author: Mike Dotty <jsonplusrpc@dt.mg>

1 Overview

JSON+RPC is a programming interface style.

2 Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are not used in this document, as the author finds the RFC 2119 a bit dubious: it is not clear WHO is required to do WHAT, on WHOSE AUTHORITY, and WHAT THE CONSEQUENCES ARE if the requirements are not fulfilled.

3 Compatibility

The JSON+RPC specification is expected to perpetually stay at version 1.0, so there are no compatibility considerations.

4 Protocol

Expose functionality using RPC (requests and responses), use JSON as a serialization format. You have a JSON+RPC interface.

5 Examples

Basically every API invented in the last 20 years that is not strictly REST/HATEOAS.

6 License

The JSON+RPC 1.0 specification is distributed under CC0 1.0.


JSON+RPC vs. JSON-RPC

JSON-RPC prescribes a specific protocol: it introduces methods, method names, parameters (positional or named, but not both), correlation identifiers, error values and their taxonomy, and request batching.

JSON+RPC acknowledges that, on the one hand, JSON-RPC is too straight-jacketed and that makes it hard to express some interfaces (streaming responses? unsolicited tack-in-to-other-response events?), and, on the other hand, is too handwavy and does not help to automatically produce valuable code from the interface description, so JSON+RPC does away with all of it.

JSON+RPC is a convenient name to put onto your interface description instead of saying, "This interface is in RPC style and uses JSON as a serialization format": a designer is free to design whatever interface is needed for the task at hand.

What is JSON?

What is RPC?

Seriously?

What is DVD?

A chandelier ornament in the form of a shiny disc that previously was used to carry data around.

HP developed a writable DVD disc and named it DVD+R. Pioneer developed a writable DVD disc and named it DVD-R. We, customers, groaned.

What uses JSON+RPC?

All software that uses JSON-RPC has been unwittingly using JSON+RPC, so it's got a pretty broad user base for a protocol that's less than one year old!

Moreover, all the other software whose designers looked at JSON-RPC and decided to roll their own RPC using JSON as a serialization format also use JSON+RPC.

GraphQL too.

Is this a joke?

Not really. It is useful to have a name for a quite common interface style on the Web: RPC with JSON as a serialization format.

JSON-RPC is already taken by a specific realization of this interface style, whose the name alone and the presence of a specification probably explains the (admittedly modest) popularity it enjoys.

JSON+RPC is definitely a tongue-in-cheek name and a play on JSON-RPC. Hopefully, enough engineers remember DVD-R/DVD+R era, so the name won't be too confusing at the beginning. If/when it becomes entrenched, it won't matter that nobody remembers DVDs anymore.