Did you know ... Search Documentation:
Pack logtalk -- logtalk-3.98.0/docs/apis/_sources/json_rpc_0.rst.txt

.. index:: single: json_rpc .. _json_rpc/0:

.. rst-class:: right

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:0 | Date: 2026-02-24

| Compilation flags: | static, context_switching_calls

| Uses: | :ref:`json <json/0>` | :ref:`list <list/0>` | :ref:`reader <reader/0>`

| 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)

.. contents:: :local: :backlinks: top

Public predicates

.. index:: request/4 .. _json_rpc/0::request/4:

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

.. index:: request/3 .. _json_rpc/0::request/3:

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

.. index:: notification/3 .. _json_rpc/0::notification/3:

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

.. index:: notification/2 .. _json_rpc/0::notification/2:

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

.. index:: response/3 .. _json_rpc/0::response/3:

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

.. index:: error_response/4 .. _json_rpc/0::error_response/4:

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

.. index:: error_response/5 .. _json_rpc/0::error_response/5:

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

.. index:: parse_error/1 .. _json_rpc/0::parse_error/1:

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

.. index:: invalid_request/1 .. _json_rpc/0::invalid_request/1:

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

.. index:: method_not_found/2 .. _json_rpc/0::method_not_found/2:

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

.. index:: invalid_params/2 .. _json_rpc/0::invalid_params/2:

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

.. index:: internal_error/2 .. _json_rpc/0::internal_error/2:

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

.. index:: encode/2 .. _json_rpc/0::encode/2:

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

.. index:: decode/2 .. _json_rpc/0::decode/2:

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

.. index:: is_request/1 .. _json_rpc/0::is_request/1:

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

.. index:: is_notification/1 .. _json_rpc/0::is_notification/1:

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

.. index:: is_response/1 .. _json_rpc/0::is_response/1:

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

.. index:: is_error_response/1 .. _json_rpc/0::is_error_response/1:

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

.. index:: is_batch/1 .. _json_rpc/0::is_batch/1:

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

.. index:: id/2 .. _json_rpc/0::id/2:

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

.. index:: method/2 .. _json_rpc/0::method/2:

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

.. index:: params/2 .. _json_rpc/0::params/2:

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

.. index:: result/2 .. _json_rpc/0::result/2:

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

.. index:: error/2 .. _json_rpc/0::error/2:

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

.. index:: error_code/2 .. _json_rpc/0::error_code/2:

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

.. index:: error_message/2 .. _json_rpc/0::error_message/2:

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

.. index:: error_data/2 .. _json_rpc/0::error_data/2:

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

.. index:: write_message/2 .. _json_rpc/0::write_message/2:

write_message/2 ^^^^^^^^^^^^^^^^^^^

Writes a JSON-RPC 2.0 message to an output 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

.. index:: read_message/2 .. _json_rpc/0::read_message/2:

read_message/2 ^^^^^^^^^^^^^^^^^^

Reads a JSON-RPC 2.0 message from an input 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

.. index:: write_framed_message/2 .. _json_rpc/0::write_framed_message/2:

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

.. index:: read_framed_message/2 .. _json_rpc/0::read_framed_message/2:

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)