JSON-RPC RFC

XIDL JSON-RPC Mapping Specification

This page defines the mapping rules from XIDL interface to JSON-RPC APIs, including:

• Method name resolution
• Request parameter mapping
• Result object mapping
• Attribute rules
• Error handling recommendations

Scope

This RFC defines the JSON-RPC 2.0 application layer model, not specific network transport protocols.

Basic Message Shape

Request example:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "pkg.Interface.method",
  "params": { "arg": 1 }
}

Response example:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": { "ok": true }
}

Error example:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "method not found",
    "data": null
  }
}

Method Name Resolution

The method name is constructed by concatenating the module path, interface name, and operation name:

• With module: {module_path}.{interface}.{method}
• Without module: {interface}.{method}

HTTP-related annotations do not affect JSON-RPC method names.

Parameter Mapping

The request params is always modeled as an object.

Rules:

• Parameter keys use the parameter names by default.
• in and inout parameters appear on the request side.
• out parameters do not appear on the request side.

Methods with zero parameters typically result in an empty object {}.

Result Mapping

The result set consists of:

• The return value.
• All out parameters.
• All inout parameters.

The JSON-RPC result is uniformly modeled as an object.

Rules:

• No output -> {}
• Only return value -> { "return": <value> }
• When out / inout are present, the return value field name is fixed as return.

Attribute Mapping

Each attribute generates implicit operations:

• get_attribute_<name>
• set_attribute_<name>

These implicit operations then generate method names and parameter/result objects according to normal JSON-RPC rules.

Type Mapping Notes

This RFC is more concerned with the JSON shape than target language implementation details.

Common interpretations:

• sequence<T> -> Array
• map<K, V> -> Object or map structure
• string -> JSON string
• Numeric scalars -> JSON number

Error Handling Recommendations

It is recommended to reuse JSON-RPC standard error codes:

• Parse error: -32700
• Invalid request: -32600
• Method not found: -32601
• Invalid params: -32602
• Internal error: -32603

Common mapping recommendations:

• Parameter decoding failure -> Invalid params
• Unknown method -> Method not found
• Internal processing failure -> Server error or Internal error

Runtime Validation

• Missing or invalid method -> invalid request
• Parameter decoding failure -> invalid params
• Unknown method -> method not found
• Request/response id mismatch -> protocol error

Transport Notes

This RFC remains transport-agnostic.

The Rust runtime in the current repository may use:

• Line-delimited JSON
• Request/response channels based on streaming I/O

However, these are implementation details and not part of the protocol definition.