JSON-RPC

Call JSON-RPC 2.0 services over HTTP, and check their results and their errors, against their OpenRPC documents.

Register the service once, usually in the Background:

Given the depots jsonrpc service with the following properties:
  | url     | http://localhost:8400/rpc |
  | openrpc | rpc.discover              |

• Params come from a table (by name, set as the REST pack’s request properties are) or a doc string (an object by name, or an array by position).
• The checks read the service’s last call in the scenario. A call that answers an error does not fail the step that makes it: check its error.
• OpenRPC: an openrpc row names the service’s OpenRPC document: a file of the project, a URL, or rpc.discover to ask the service for it. Every call’s params are then checked against its method before it is sent, and every result and error when it comes back. A call that breaks the document fails the step that makes it, and names the rule it broke.

OpenRPC findings have keys and levels, like the REST pack’s OpenAPI findings:

Key	Found when
validation.method.unknown	the document has no such method
validation.params.structure	the params are by name for a method that takes them by position, or the other way round
validation.params.missing	a required param is missing
validation.params.unknown	a param the method does not have
validation.params.schema.<keyword>	a param breaks a keyword of its schema (required, type, pattern…)
validation.result.schema.<keyword>	the result breaks a keyword of its schema
validation.error.unknown	the error is not one the method declares, nor one of JSON-RPC’s own (-32700, -32600 to -32603, -32000 to -32099)

• Levels: ERROR (or FAIL) fails the step, WARN and INFO log the finding, IGNORE drops it. Every finding is an ERROR unless packs.jsonrpc.openrpc.levels in axx.yaml, or the scenario’s the OpenRPC validation levels are:, says otherwise.
• Keys cover the keys below them: validation.params sets every params finding; the most specific key set wins.
• Secrets stay secret: ${env:..} values in the properties are masked in logs and failures, and ${token:..} names a token of the scenario.

Add it to a project with axx pack add jsonrpc.

Settings

In axx.yaml, under packs.jsonrpc:

Setting	Takes	Values
openrpc.levels	Validation key -> ERROR (or FAIL), WARN, INFO or IGNORE, for every scenario.	names and values

Steps

jsonrpc.service

Given the {word} jsonrpc service with the following properties:
  | property | value |

The table may start with the row naming its columns, as above, or go straight to its rows.

Register a JSON-RPC 2.0 service, which takes calls over HTTP, under a name.

Parameter	Takes	For example
{word}	one word, with no spaces	parcels, PX-4101

Property	Takes	Default
url	the URL calls are posted to	required
header.<name>	a header sent with every call, such as header.Authorization
timeout	how long a call may take, like 5s	10s
openrpc	the service’s OpenRPC document, which its calls are checked against: a file of the project, a URL, or rpc.discover to ask the service for it

Values are expanded (${env:..}, ${sys:..}, ${token:..}); what ${env:..} references expand to is masked everywhere.

Example:

Given the depots jsonrpc service with the following properties:
  | url     | http://localhost:8400/rpc |
  | openrpc | rpc.discover              |
Given the depots jsonrpc service with the following properties:
  | url                  | https://depots.parcels.example/rpc |
  | header.Authorization | Bearer ${env:DEPOTS_TOKEN}         |
  | openrpc              | openrpc/depots.json                |

Since 0.1.5.

jsonrpc.call

When the {word} method is called on the {word} jsonrpc service

Call a method without params.

Parameter	Takes	For example
{word}	one word, with no spaces	parcels, PX-4101

Example:

When the depot.list method is called on the depots jsonrpc service

Since 0.1.5.

jsonrpc.call.params

When the {word} method is called on the {word} jsonrpc service with the following params:
  | path | value |

The table may start with the row naming its columns, as above, or go straight to its rows.

Call a method with params by name, from the table.

Parameter	Takes	For example
{word}	one word, with no spaces	parcels, PX-4101

Each row is a param, or a path into one (address.postcode), and its value: numbers and booleans are JSON’s, double quotes make a value text, null is null and undefined leaves it out.

Example:

When the parcel.hold method is called on the depots jsonrpc service with the following params:
  | reference | PX-RPC-7101 |
  | until     | 2026-10-02  |

Since 0.1.5.

jsonrpc.call.doc

When the {word} method is called on the {word} jsonrpc service with the params:
  """
  ...
  """

Call a method with the params of the doc string: an object, by name, or an array, by position.

Parameter	Takes	For example
{word}	one word, with no spaces	parcels, PX-4101

Example:

When the parcel.get method is called on the depots jsonrpc service with the params:
  """
  ["PX-RPC-7102"]
  """

Since 0.1.5.

jsonrpc.result

Then the {word} jsonrpc service's result has the following properties:
  | path | value |

The table may start with the row naming its columns, as above, or go straight to its rows.

Check the result of the service’s last call.

Parameter	Takes	For example
{word}	one word, with no spaces	parcels, PX-4101

Each row is a path into the result (a field name, a dotted path or a JSONPath) and its value, compared as text: null for null and undefined for absent.

Example:

Then the depots jsonrpc service's result has the following properties:
  | reference | PX-RPC-7101 |
  | status    | ON_HOLD     |

Since 0.1.5.

jsonrpc.result.is

Then the {word} jsonrpc service's result is {string}

Check the whole result of the service’s last call: a text’s text, or the JSON of any other result.

Parameter	Takes	For example
{word}	one word, with no spaces	parcels, PX-4101
{string}	text in double or single quotes, which the step leaves out	"Get a quote", 'Express'

Example:

Then the depots jsonrpc service's result is 'true'

Since 0.1.5.

jsonrpc.error

Then the {word} jsonrpc service answered the error {int}[[ with a message containing {string}]]

Check the error code the service’s last call answered, and the text its message contains.

Parameter	Takes	For example
{word}	one word, with no spaces	parcels, PX-4101
{int}	a whole number	200, 3
{string}	text in double or single quotes, which the step leaves out	"Get a quote", 'Express'

Variants, the parts in [[...]] said or left out:

• the {word} jsonrpc service answered the error {int}
• the {word} jsonrpc service answered the error {int} with a message containing {string}

Example:

Then the depots jsonrpc service answered the error -32602
Then the depots jsonrpc service answered the error -32010 with a message containing 'out for delivery'

Since 0.1.5.

jsonrpc.error.properties

Then the {word} jsonrpc service's error has the following properties:
  | path | value |

The table may start with the row naming its columns, as above, or go straight to its rows.

Check the error the service’s last call answered: its code, its message and its data.

Parameter	Takes	For example
{word}	one word, with no spaces	parcels, PX-4101

Each row is a path into the error object (code, message, data.reason) and its value, compared as text: null for null and undefined for absent.

Example:

Then the depots jsonrpc service's error has the following properties:
  | code        | -32010           |
  | data.status | OUT_FOR_DELIVERY |

Since 0.1.5.

jsonrpc.openrpc.levels

Given the OpenRPC validation levels are:
  | validation key | level |

The table may start with the row naming its columns, as above, or go straight to its rows.

Set the level of OpenRPC validation findings for this scenario, on every JSON-RPC service it calls.

• A key also sets the keys below it: validation.params relaxes validation.params.schema.required too. The most specific key set wins.
• The rows are merged over packs.jsonrpc.openrpc.levels of axx.yaml.
• The pack’s documentation lists the keys, and what each level does.

A row is a validation key and its level: ERROR (or FAIL), WARN, INFO or IGNORE. The key must be one the pack reports, or a prefix of such keys, like validation.params: any other fails the step, which names the closest keys.

Example:

Given the OpenRPC validation levels are:
  | validation.params | IGNORE |

Since 0.1.5.