object

# `json_rpc`

JSON-RPC 2.0 protocol encoding and decoding. Provides predicates for constructing and parsing JSON-RPC 2.0 request, notification, response, and error objects. Uses the `json` library for JSON parsing and generation.

Availability:
`logtalk_load(json_rpc(loader))`
Author: Paulo Moura
Version: 1:0:4
Date: 2026-07-13
Compilation flags:
`static, context_switching_calls`
Uses:
json
list
reader
Remarks:

> - Specification: Implements the JSON-RPC 2.0 specification (https://www.jsonrpc.org/specification).

> - JSON representation: Uses the `json` library default representation: curly terms for objects, dashes for pairs, and atoms for strings.

> - Request: A JSON-RPC 2.0 request is represented as `{jsonrpc-'2.0', method-Method, params-Params, id-Id}`.

> - Notification: A JSON-RPC 2.0 notification is represented as `{jsonrpc-'2.0', method-Method, params-Params}`.

> - Successful response: A JSON-RPC 2.0 successful response is represented as `{jsonrpc-'2.0', result-Result, id-Id}`.

> - Error response: A JSON-RPC 2.0 error response is represented as `{jsonrpc-'2.0', error-{code-Code, message-Message}, id-Id}` or `{jsonrpc-'2.0', error-{code-Code, message-Message, data-Data}, id-Id}`.

> - Batch request: A JSON-RPC 2.0 batch request is represented as a list of request and/or notification terms.

> - Error codes: Standard error codes: -32700 (parse error), -32600 (invalid request), -32601 (method not found), -32602 (invalid params), -32603 (internal error). Server errors: -32000 to -32099.

Inherited public predicates:
(none)

## Public predicates

### `request/4`

Constructs a JSON-RPC 2.0 request term.

Compilation flags:
`static`
Template:
`request(Method,Params,Id,Request)`
Mode and number of proofs:
`request(+atom,+list,+nonvar,--compound)` - `one`

### `request/3`

Constructs a JSON-RPC 2.0 request term with no parameters.

Compilation flags:
`static`
Template:
`request(Method,Id,Request)`
Mode and number of proofs:
`request(+atom,+nonvar,--compound)` - `one`

### `notification/3`

Constructs a JSON-RPC 2.0 notification term (a request without an id).

Compilation flags:
`static`
Template:
`notification(Method,Params,Notification)`
Mode and number of proofs:
`notification(+atom,+list,--compound)` - `one`

### `notification/2`

Constructs a JSON-RPC 2.0 notification term with no parameters.

Compilation flags:
`static`
Template:
`notification(Method,Notification)`
Mode and number of proofs:
`notification(+atom,--compound)` - `one`

### `response/3`

Constructs a JSON-RPC 2.0 successful response term.

Compilation flags:
`static`
Template:
`response(Result,Id,Response)`
Mode and number of proofs:
`response(+nonvar,+nonvar,--compound)` - `one`

### `error_response/4`

Constructs a JSON-RPC 2.0 error response term with a null id (used when the request id cannot be determined).

Compilation flags:
`static`
Template:
`error_response(Code,Message,Id,ErrorResponse)`
Mode and number of proofs:
`error_response(+integer,+atom,+nonvar,--compound)` - `one`

### `error_response/5`

Constructs a JSON-RPC 2.0 error response term with additional error data.

Compilation flags:
`static`
Template:
`error_response(Code,Message,Data,Id,ErrorResponse)`
Mode and number of proofs:
`error_response(+integer,+atom,+nonvar,+nonvar,--compound)` - `one`

### `parse_error/1`

Constructs a JSON-RPC 2.0 parse error response (-32700) with a null id.

Compilation flags:
`static`
Template:
`parse_error(ErrorResponse)`
Mode and number of proofs:
`parse_error(--compound)` - `one`

### `invalid_request/1`

Constructs a JSON-RPC 2.0 invalid request error response (-32600) with a null id.

Compilation flags:
`static`
Template:
`invalid_request(ErrorResponse)`
Mode and number of proofs:
`invalid_request(--compound)` - `one`

### `method_not_found/2`

Constructs a JSON-RPC 2.0 method not found error response (-32601).

Compilation flags:
`static`
Template:
`method_not_found(Id,ErrorResponse)`
Mode and number of proofs:
`method_not_found(+nonvar,--compound)` - `one`

### `invalid_params/2`

Constructs a JSON-RPC 2.0 invalid params error response (-32602).

Compilation flags:
`static`
Template:
`invalid_params(Id,ErrorResponse)`
Mode and number of proofs:
`invalid_params(+nonvar,--compound)` - `one`

### `internal_error/2`

Constructs a JSON-RPC 2.0 internal error response (-32603).

Compilation flags:
`static`
Template:
`internal_error(Id,ErrorResponse)`
Mode and number of proofs:
`internal_error(+nonvar,--compound)` - `one`

### `encode/2`

Encodes a JSON-RPC 2.0 term (request, notification, response, error, or batch) into a JSON atom.

Compilation flags:
`static`
Template:
`encode(Term,JSON)`
Mode and number of proofs:
`encode(+compound,--atom)` - `one`

### `decode/2`

Decodes a JSON atom into a JSON-RPC 2.0 term (request, notification, response, error, or batch).

Compilation flags:
`static`
Template:
`decode(JSON,Term)`
Mode and number of proofs:
`decode(+atom,--compound)` - `one_or_error`
Exceptions:
`JSON` is a variable:
`instantiation_error`
`JSON` is neither a variable nor a valid JSON atom term or does not contain parsable JSON by the implementation:
`domain_error(json_source,JSON)`

### `is_request/1`

True if the term is a valid JSON-RPC 2.0 request (has jsonrpc, method, and id fields).

Compilation flags:
`static`
Template:
`is_request(Term)`
Mode and number of proofs:
`is_request(+compound)` - `zero_or_one`

### `is_notification/1`

True if the term is a valid JSON-RPC 2.0 notification (has jsonrpc and method fields but no id field).

Compilation flags:
`static`
Template:
`is_notification(Term)`
Mode and number of proofs:
`is_notification(+compound)` - `zero_or_one`

### `is_response/1`

True if the term is a valid JSON-RPC 2.0 successful response (has jsonrpc, result, and id fields).

Compilation flags:
`static`
Template:
`is_response(Term)`
Mode and number of proofs:
`is_response(+compound)` - `zero_or_one`

### `is_error_response/1`

True if the term is a valid JSON-RPC 2.0 error response (has jsonrpc, error, and id fields).

Compilation flags:
`static`
Template:
`is_error_response(Term)`
Mode and number of proofs:
`is_error_response(+compound)` - `zero_or_one`

### `is_batch/1`

True if the term is a valid JSON-RPC 2.0 batch (a non-empty list).

Compilation flags:
`static`
Template:
`is_batch(Term)`
Mode and number of proofs:
`is_batch(+compound)` - `zero_or_one`

### `id/2`

Extracts the id field from a JSON-RPC 2.0 message.

Compilation flags:
`static`
Template:
`id(Message,Id)`
Mode and number of proofs:
`id(+compound,--nonvar)` - `zero_or_one`

### `method/2`

Extracts the method field from a JSON-RPC 2.0 request or notification.

Compilation flags:
`static`
Template:
`method(Message,Method)`
Mode and number of proofs:
`method(+compound,--atom)` - `zero_or_one`

### `params/2`

Extracts the params field from a JSON-RPC 2.0 request or notification.

Compilation flags:
`static`
Template:
`params(Message,Params)`
Mode and number of proofs:
`params(+compound,--nonvar)` - `zero_or_one`

### `result/2`

Extracts the result field from a JSON-RPC 2.0 response.

Compilation flags:
`static`
Template:
`result(Message,Result)`
Mode and number of proofs:
`result(+compound,--nonvar)` - `zero_or_one`

### `error/2`

Extracts the error field from a JSON-RPC 2.0 error response.

Compilation flags:
`static`
Template:
`error(Message,Error)`
Mode and number of proofs:
`error(+compound,--compound)` - `zero_or_one`

### `error_code/2`

Extracts the error code from a JSON-RPC 2.0 error response.

Compilation flags:
`static`
Template:
`error_code(Message,Code)`
Mode and number of proofs:
`error_code(+compound,--integer)` - `zero_or_one`

### `error_message/2`

Extracts the error message from a JSON-RPC 2.0 error response.

Compilation flags:
`static`
Template:
`error_message(Message,ErrorMessage)`
Mode and number of proofs:
`error_message(+compound,--atom)` - `zero_or_one`

### `error_data/2`

Extracts the error data from a JSON-RPC 2.0 error response. Fails if no data field is present.

Compilation flags:
`static`
Template:
`error_data(Message,Data)`
Mode and number of proofs:
`error_data(+compound,--nonvar)` - `zero_or_one`

### `write_message/2`

Writes a JSON-RPC 2.0 message to an output text stream as a single line of JSON followed by a newline. Flushes the output stream after writing.

Compilation flags:
`static`
Template:
`write_message(Output,Message)`
Mode and number of proofs:
`write_message(+stream,+compound)` - `one`

### `read_message/2`

Reads a JSON-RPC 2.0 message from an input text stream. Reads a line of JSON text and parses it. Fails at end of stream.

Compilation flags:
`static`
Template:
`read_message(Input,Message)`
Mode and number of proofs:
`read_message(+stream,--compound)` - `zero_or_one`

### `write_framed_message/2`

Writes a JSON-RPC 2.0 message to an output stream using Content-Length framing (as used by LSP style protocols). The message is preceded by a `Content-Length: N\r\n\r\n` header where `N` is the byte length of the JSON body. Flushes the output stream after writing.

Compilation flags:
`static`
Template:
`write_framed_message(Output,Message)`
Mode and number of proofs:
`write_framed_message(+stream,+compound)` - `one`

### `read_framed_message/2`

Reads a JSON-RPC 2.0 message from an input stream using Content-Length framing (as used by LSP style protocols). Reads a `Content-Length: N\r\n\r\n` header followed by exactly `N` bytes of JSON body. Fails at end of stream or if the header is missing or malformed.

Compilation flags:
`static`
Template:
`read_framed_message(Input,Message)`
Mode and number of proofs:
`read_framed_message(+stream,--compound)` - `zero_or_one`

## Protected predicates

(no local declarations; see entity ancestors if any)

## Private predicates

(no local declarations; see entity ancestors if any)

## Operators

(none)