DEV Community: kuangren chu

Resource-Oriented JSON-RPC (RO-JRPC) 1.0

kuangren chu — Thu, 30 Apr 2026 11:57:05 +0000

Resource-Oriented JSON-RPC (RO-JRPC) 1.0

A Backward-Compatible Structured Routing Extension for JSON-RPC 2.0
From: https://github.com/ggzy12345/ro-jrpc/

Field	Value
Status	Draft
Category	Standards Track
Version	1.0 Draft
Depends on	JSON-RPC 2.0

Abstract
Terminology
Compatibility
Request Object
Semantics
Canonical Method Mapping
Example Requests
Responses
Receiver Behavior
Notifications
Discovery
Authorization Model
Transport Independence
Implementation Guidance
Security Considerations
Versioning
Rationale
Caching
Async Results
Example: AI Agent Usage
Example: CLI Usage

1. Abstract

This specification defines Resource-Oriented JSON-RPC (RO-JRPC), a backward-compatible extension to JSON-RPC 2.0 that standardizes structured routing fields for request messages.

RO-JRPC introduces the following extension fields:

resource
target
verb
subresource
parent

These fields make explicit the semantics commonly encoded inside JSON-RPC method strings such as:

user.create
task.cancel
file.read

RO-JRPC preserves compatibility with existing JSON-RPC 2.0 tooling while enabling improved:

Authorization
Capability discovery
Analytics
Code generation
Agent/tool protocols
CLI/local IPC systems
Async result routing

2. Terminology

The key words MUST, SHOULD, MAY, MUST NOT, and SHOULD NOT are to be interpreted as described in RFC 2119.

3. Compatibility

A valid RO-JRPC request MUST also be a valid JSON-RPC 2.0 request.

Therefore:

jsonrpc MUST equal "2.0"
method MUST be present
id follows JSON-RPC 2.0 rules
Notifications remain supported

RO-JRPC adds optional members and semantics only.

4. Request Object

4.1 Standard Members

RO-JRPC inherits all JSON-RPC 2.0 request members:

Member	Requirement
`jsonrpc`	REQUIRED
`method`	REQUIRED
`params`	OPTIONAL
`id`	OPTIONAL

4.2 Extension Members

All extension members are OPTIONAL. resource and verb MUST appear together — one without the other is invalid. subresource and parent MUST NOT appear unless resource is also present.

Member	Type	Meaning
`resource`	`string`	Logical entity class or collection
`target`	`string \	number`
`verb`	`string`	Action to perform
`subresource`	`string`	Nested entity class owned by `resource`
`parent`	`string \	number`
`meta`	`object`	Optional metadata (servers SHOULD NOT trust)
`cache`	`string \	object`
`request_id`	`string \	number`

5. Semantics

5.1 Resource

resource identifies the logical subject of the operation.

Examples: user, task, file, repo, session, tool, agent

5.2 Target

target identifies a specific instance of a resource.

Examples: 42, "abc123", "/tmp/demo.txt", "session-9"

5.3 Verb

verb identifies the requested action.

Recommended verbs:

Verb	Meaning
`get`	Retrieve a single resource
`list`	Retrieve multiple resources
`create`	Create a new resource
`update`	Modify an existing resource
`delete`	Remove a resource
`execute`	Run a procedure or tool
`cancel`	Abort an in-progress operation
`watch`	Subscribe to resource changes
`describe`	Return capability metadata
`lock`	Acquire a lock on a resource
`unlock`	Release a lock on a resource

Async result verbs:

Verb	Meaning
`yield`	Intermediate async result; more messages expected
`return`	Final async result; no further messages expected

yield and return are used in result messages flowing back to the originating client (see §19). They SHOULD NOT be used in client-to-server requests.

Implementations MAY define custom verbs.

5.4 Sub-Resource

subresource identifies a nested entity class that is owned by and scoped to a resource.

Examples: repo → issue, project → task, session → message, org → member

Rules:

subresource MUST NOT be present unless resource is also present.
Nesting beyond one level (sub-sub-resources) is explicitly out of scope. If deeper nesting is required, the resource model SHOULD be flattened.
When subresource is present, target identifies a specific instance of the subresource, not of resource.

5.5 Parent

parent identifies the specific instance of resource that owns the subresource being addressed.

parent MUST NOT be present unless subresource is also present.
parent plays the same role for resource that target plays for subresource.

6. Canonical Method Mapping

When resource and verb are present, method MUST equal:

Without subresource: <resource>.<verb>
With subresource: <resource>.<subresource>.<verb>

`resource`	`subresource`	`verb`	`method`
`user`	—	`create`	`user.create`
`task`	—	`cancel`	`task.cancel`
`repo`	—	`clone`	`repo.clone`
`repo`	`issue`	`get`	`repo.issue.get`
`project`	`task`	`list`	`project.task.list`
`org`	`member`	`delete`	`org.member.delete`
`job`	—	`yield`	`job.yield`
`job`	—	`return`	`job.return`

6.1 Target Exclusion Rule

target SHOULD NOT be embedded in method.

Preferred:

{
  "method": "user.get",
  "resource": "user",
  "target": "42",
  "verb": "get"
}

Avoid:

user.42.get

7. Example Requests

7.1 Create User

{
  "jsonrpc": "2.0",
  "method": "user.create",
  "resource": "user",
  "verb": "create",
  "params": { "name": "Alice" },
  "id": 1
}

7.2 Get User

{
  "jsonrpc": "2.0",
  "method": "user.get",
  "resource": "user",
  "target": "42",
  "verb": "get",
  "id": 2
}

7.3 Cancel Task

{
  "jsonrpc": "2.0",
  "method": "task.cancel",
  "resource": "task",
  "target": "123",
  "verb": "cancel",
  "id": "abc"
}

7.4 Get a Sub-Resource (Issue on a Repo)

{
  "jsonrpc": "2.0",
  "method": "repo.issue.get",
  "resource": "repo",
  "parent": "99",
  "subresource": "issue",
  "target": "7",
  "verb": "get",
  "id": 3
}

7.5 List Sub-Resources (Tasks in a Project)

{
  "jsonrpc": "2.0",
  "method": "project.task.list",
  "resource": "project",
  "parent": "42",
  "subresource": "task",
  "verb": "list",
  "id": 4
}

7.6 Create a Sub-Resource (Message in a Session)

{
  "jsonrpc": "2.0",
  "method": "session.message.create",
  "resource": "session",
  "parent": "session-9",
  "subresource": "message",
  "verb": "create",
  "params": { "content": "Hello" },
  "id": 5
}

8. Responses

Responses MUST remain compliant with JSON-RPC 2.0.

Success:

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

Error:

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32600,
    "message": "Invalid Request: verb not supported"
  },
  "id": "abc"
}

9. Receiver Behavior

9.1 Structured Requests

If resource and verb are present, receivers MUST route using those members.

If subresource is also present, receivers MUST route using resource, subresource, and verb together.

9.2 Legacy Requests

If only method is present, receivers MAY route using method parsing or legacy dispatch.

9.3 Mismatch Handling

If method, resource, subresource, and verb are inconsistent — for example:

method   = "user.create"
resource = "task"
verb     = "delete"

Or:

method      = "repo.issue.get"
resource    = "repo"
subresource = "comment"
verb        = "get"

The receiver MUST reject with -32600 Invalid Request.

9.4 Co-presence Rules

The following combinations are invalid and MUST be rejected with -32600:

Condition	Invalid because
`resource` present, `verb` absent	Incomplete structured request
`verb` present, `resource` absent	Incomplete structured request
`subresource` present, `resource` absent	Sub-resource requires parent resource
`parent` present, `subresource` absent	`parent` is meaningless without sub-resource
`target` present, `resource` absent	Target has no resource context

10. Notifications

Notifications are requests without id. No response is sent.

{
  "jsonrpc": "2.0",
  "method": "log.create",
  "resource": "log",
  "verb": "create",
  "params": { "message": "started" }
}

11. Discovery

Servers SHOULD support rpc.describe.

Request:

{
  "jsonrpc": "2.0",
  "method": "rpc.describe",
  "resource": "rpc",
  "verb": "describe",
  "id": 1
}

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "protocol": "ro-jrpc",
    "version": "1.0-draft",
    "resources": [
      {
        "name": "user",
        "verbs": ["create", "get", "update", "delete"]
      },
      {
        "name": "task",
        "verbs": ["list", "cancel"]
      },
      {
        "name": "repo",
        "verbs": ["get", "list", "clone"],
        "subresources": [
          { "name": "issue", "verbs": ["get", "list", "create", "delete"] }
        ]
      }
    ]
  },
  "id": 1
}

The protocol and version fields in the result allow clients to confirm RO-JRPC support and negotiate behavior. Servers SHOULD include both.

12. Authorization Model

RO-JRPC enables structured policy systems. The full authorization tuple is:

resource [+ subresource] + verb [+ target | parent]

This is the primary advantage over method-string ACLs — policies can be written at any granularity without string parsing.

Flat resource policies:

allow  user:create
allow  task:get          target=*
deny   file:delete       target=*
allow  file:delete       target=own

Sub-resource policies:

allow  repo:issue:get    parent=*
allow  repo:issue:create parent=own
deny   org:member:delete parent=*

Target wildcards:

target=* — any instance
target=own — only instances owned by the requesting identity
target=<id> — a specific instance

The policy syntax above is illustrative. Implementations MAY define their own policy language; what RO-JRPC standardizes is the tuple structure, not the policy format.

13. Transport Independence

RO-JRPC MAY be used over:

stdio
pipes
Unix domain sockets
TCP
HTTP
WebSocket
Child-process IPC

14. Implementation Guidance

Preferred Internal Router API

// Flat resources
router.resource("user").verb("create", handler)
router.resource("task").verb("cancel", handler)

// Sub-resources
router.resource("repo").subresource("issue").verb("get", handler)
router.resource("project").subresource("task").verb("list", handler)

// Async result verbs
router.resource("job").verb("yield", handler)
router.resource("job").verb("return", handler)

Compatibility Adapter

If structured members are absent, receivers MAY parse method:

user.create        →  resource=user  verb=create
repo.issue.get     →  resource=repo  subresource=issue  verb=get

Single-segment methods (e.g. ping, health) MAY be treated as plain JSON-RPC 2.0 and routed via legacy dispatch. Three-or-more-segment methods that do not match <resource>.<subresource>.<verb> SHOULD be rejected with -32600.

15. Security Considerations

Servers MUST validate:

Allowed resources
Allowed verbs
Target ownership
Params schema

Servers SHOULD NOT trust client-supplied meta.

Receivers SHOULD validate that request_id in async result messages references a known outstanding request before dispatching.

16. Versioning

RO-JRPC does not alter jsonrpc. Requests MUST continue using:

"jsonrpc": "2.0"

Protocol capability MAY be advertised through rpc.describe or transport negotiation.

17. Rationale

JSON-RPC method strings commonly encode structure informally:

user.create
task.cancel
tool.execute

RO-JRPC standardizes this widespread convention into explicit, machine-readable fields — enabling routing, authorization, and tooling that do not require method string parsing.

18. Caching

Both client and server MAY maintain their own cache independently. No negotiation is required for the basic case.

The natural cache key is: resource + verb + target (plus subresource + parent when present). Verbs get and list are cacheable by nature; create, update, and delete are not. Implementations SHOULD invalidate cached entries for a resource when a mutating verb (create, update, delete) is observed for that resource.

18.1 Cache Directive on Responses

Servers MAY include a cache field on responses to hint TTL to clients:

{
  "jsonrpc": "2.0",
  "result": { "id": "42", "name": "Alice" },
  "cache": { "max-age": 60 },
  "id": 1
}

Field	Type	Meaning
`max-age`	`integer`	Seconds the result may be reused by the client

18.2 Cache Directive on Requests

Clients MAY include a cache field on requests to bypass the server cache:

{
  "jsonrpc": "2.0",
  "method": "user.get",
  "resource": "user",
  "verb": "get",
  "target": "42",
  "cache": "no-cache",
  "id": 1
}

Value	Meaning
`no-cache`	Server SHOULD NOT serve a cached result

Implementations MAY extend the cache object with additional directives. Unrecognised directives MUST be ignored.

19. Async Results

RO-JRPC supports async result delivery through resource-oriented result messages. Whether delivery is push or pull, and whether the originating request is sync or async, is left to the implementation and transport.

19.1 Async Result Verbs

Two reserved verbs are defined for result messages flowing from server to client:

Verb	Meaning
`yield`	Intermediate result; more messages expected
`return`	Final result; no further messages will be sent

These verbs SHOULD NOT be used in client-to-server requests.

19.2 Result Message Structure

An async result message is itself a resource-oriented RO-JRPC message. The resource in the result does not need to match the resource of the originating request — for example, a long-running operation initiated on any resource may deliver results as a job resource.

The id field in the result message SHOULD match the id of the originating request when the result is delivered on the same connection or channel. When delivered on a different channel, or when there is no single originating request (pure event-driven), request_id MAY be used instead.

19.3 request_id

request_id is an optional field that explicitly correlates an async result back to the originating request. It SHOULD be included when:

The result is delivered on a different channel or connection from the original request
The result resource differs from the request resource (e.g. job.yield in response to attachment.create)

request_id MAY be omitted for pure event-driven cases where no single originating request exists, such as session events scoped by target.

19.4 Examples

Intermediate result (upload attachment → job):

{
  "jsonrpc": "2.0",
  "method": "job.yield",
  "resource": "job",
  "verb": "yield",
  "target": "job-123",
  "result": { "status": "pending", "progress": 60, "stage": "scanning" },
  "request_id": "req-001"
}

Final result (upload attachment → job):

{
  "jsonrpc": "2.0",
  "method": "job.return",
  "resource": "job",
  "verb": "return",
  "target": "job-123",
  "result": { "status": "done", "attachmentId": "att-456" },
  "request_id": "req-001"
}

Session event (pure event-driven, no request_id):

{
  "jsonrpc": "2.0",
  "method": "session.yield",
  "resource": "session",
  "verb": "yield",
  "target": "session-9",
  "result": { "status": "pending", "content": "Thinking..." }
}

Session final result:

{
  "jsonrpc": "2.0",
  "method": "session.return",
  "resource": "session",
  "verb": "return",
  "target": "session-9",
  "result": { "status": "done", "content": "Here is your answer." }
}

19.5 Status Field

The result object SHOULD include a status field when using async result verbs:

Status	Meaning
`accepted`	Request received and queued, not yet started
`pending`	In progress, more results expected
`done`	Completed successfully
`error`	Failed; no further messages will be sent

status is a convention within result — it is not a top-level envelope field.

20. Example: AI Agent Usage

{
  "jsonrpc": "2.0",
  "method": "tool.execute",
  "resource": "tool",
  "target": "web-search",
  "verb": "execute",
  "params": { "query": "rust async" },
  "id": "req1"
}

21. Example: CLI Usage

{
  "jsonrpc": "2.0",
  "method": "build.execute",
  "resource": "build",
  "verb": "execute",
  "params": { "target": "linux" },
  "id": "1"
}

Library vs Framework: The Real Difference Between tkucli and clap

kuangren chu — Sun, 19 Apr 2026 00:15:52 +0000

When comparing tkucli and clap, most differences (syntax, config, features) are surface-level.

The deeper distinction is much simpler:

clap is a library

tkucli is a framework

That single difference changes how you build your entire CLI.

clap: a library

clap is a tool in your toolbox.

It focuses on one responsibility:

parsing arguments
validating input
generating help text

Everything else is up to you.

What that means in practice

You control how your app is structured
You decide how commands map to logic
You handle routing, errors, and flow

#[derive(Parser)]
struct Cli {
    #[command(subcommand)]
    command: Commands,
}

You call clap. It doesn’t call you.

Analogy

clap is like:

a high-end steering wheel and dashboard

It helps you drive—but you still build the entire car.

tkucli: a framework

tkucli is not just a parser—it defines the shape of your application.

You describe your CLI in cli.toml, and the framework:

generates command structure
wires routing automatically
maps arguments into typed handlers
runs your logic

What that means in practice

The framework defines the architecture
You implement handler functions
Execution flow is managed for you

[[resource]]
name = "users"

[[resource.operation]]
verb = "list"

You don’t call the framework.

The framework calls you.

Analogy

tkucli is like:

a pre-fabricated house

You don’t design every wall—you move in and start using it.

The key concept: Inversion of Control

This is the real dividing line.

clap

You control everything
You call into the library

tkucli

The framework controls the flow
You plug into predefined extension points

Why this matters

This isn’t just philosophical—it affects how you build.

Choose clap if you want flexibility

Full control over architecture
Custom execution models
Unusual or highly specialized CLI behavior

clap stays out of your way.

Choose tkucli if you want speed and consistency

Standardized command structure
Less routing boilerplate
Built-in CLI + TUI integration
Strong fit for resource-based tools

Especially useful for:

CRUD-style tools
internal platforms
infrastructure tooling

Trade-offs

	clap	tkucli
Control	High	Structured
Flexibility	Maximum	Opinionated
Setup speed	Medium	Fast
Boilerplate	Manual	Reduced
Architecture	User-defined	Framework-defined

Takeaway

The difference isn’t about “which is better”.

It’s about how much control you want over your CLI:

clap → you design everything
tkucli → you follow a system and fill in the logic

Both are valid. They just solve different problems.

Project

https://github.com/ggzy12345/tkucli

A Different Way to Build Rust CLIs: tkucli vs clap

kuangren chu — Sat, 18 Apr 2026 23:51:45 +0000

Most Rust CLIs today are built with clap—and for good reason. It’s powerful, flexible, and deeply integrated with Rust.

But there’s another approach worth exploring.

Two ways to define a CLI

clap (code-first)

#[derive(Parser)]
struct Cli {
    #[command(subcommand)]
    command: Commands,
}

You define your CLI structure directly in Rust.

tkucli (config-first)

[[resource]]
name = "users"

[[resource.operation]]
verb = "list"

You define your CLI as a schema, and the framework generates the rest.

Key differences

	clap	tkucli
Definition	Rust code	`cli.toml`
Structure	Command tree	Resource → operation
Changes	Edit code	Edit config
Boilerplate	Manual	Generated
TUI	External	Built-in

What this changes

With clap, your CLI is part of your code.

With tkucli, your CLI becomes data that drives your code.

That enables:

clearer separation between interface and logic
easier structural changes
a shared definition for CLI and TUI

When each works well

clap

You want full control in Rust
Your CLI is stable
You prefer explicit code

tkucli

Your CLI evolves frequently
You want a declarative structure
You like separating interface from implementation

Takeaway

These aren’t competing so much as different design choices:

clap → code-first CLI
tkucli → schema-driven CLI

If you’ve only used one style, it’s worth trying the other—you might find it fits certain projects better.

Project

https://github.com/ggzy12345/tkucli

A declarative CLI framework in Rust

kuangren chu — Sat, 18 Apr 2026 02:41:01 +0000

I built a declarative CLI framework in Rust (define your CLI in TOML)

Most Rust CLI tools are built with libraries like clap. They’re powerful—but also verbose.

After building a few internal tools, I kept running into the same problem:

Too much boilerplate for simple commands
Repeating argument parsing logic
Hard to manage growing CLI complexity

So I built tkucli — a declarative CLI framework for Rust.

🧠 The idea

Instead of writing Rust code to define commands, you describe your CLI in a TOML file.

You define:

commands
arguments
workflows

…and the framework handles execution.

✨ Example

Define a command:

[app]
name           = "vm-cli"
version        = "0.1.0"
description    = "A Tkucli-powered CLI"
default_output = "table"

[tui]
enabled        = true
theme          = "dark"

[[resource]]
name        = "vm"
description = "VM resource — replace with your own"

  [[resource.operation]]
  verb        = "create"
  description = "create a vm"
  args        = [{ name = "name", type = "string", required = true }]

  [[resource.operation]]
  verb        = "list"
  description = "List all examples"
  flags       = [
    { name = "limit", short = "n", type = "u32", default = "20", help = "Max results" },
  ]

  [[resource.operation]]
  verb        = "get"
  description = "Get a vm by name"
  args        = [{ name = "name", type = "string", required = true }]

  [[resource.operation]]
  verb        = "delete"
  description = "Get a vm by name"
  args        = [{ name = "name", type = "string", required = true }]

Run it:

tkucli vm-cli vm create --name first-vm

🚀 Why I built this

I wanted something that feels like:

Infrastructure-as-Code, but for CLI
Easy to extend (TUI, workflows, automation)
Great for internal tools / DevOps / homelabs

🔄 How it compares

clap → full control, but code-heavy
bash → quick, but messy at scale
tkucli → structured, declarative, fast to build

🧩 Use cases

Wrapping tools like Ansible / Terraform
Internal developer platforms
Automation CLIs
Homelab management

⚠️ What it’s NOT

This isn’t trying to replace low-level CLI frameworks.

If you need:

very custom parsing
maximum performance → use clap

💡 What I’m exploring next

Built-in TUI support (ratatui-style)
Better workflow composition
Git-backed CLI configs

🙌 Looking for feedback

I’m trying to answer a simple question:

What if building a CLI felt like writing a config, not a program?

Curious if this resonates with others building tools in Rust.

Does this solve a real pain for you?
Would you use something like this?

Happy to share repo / details if there’s interest.

DEV Community: kuangren chu

Resource-Oriented JSON-RPC (RO-JRPC) 1.0

Resource-Oriented JSON-RPC (RO-JRPC) 1.0

Table of Contents

1. Abstract

2. Terminology

3. Compatibility

4. Request Object

4.1 Standard Members

4.2 Extension Members

5. Semantics

5.1 Resource

5.2 Target

5.3 Verb

5.4 Sub-Resource

5.5 Parent

6. Canonical Method Mapping

6.1 Target Exclusion Rule

7. Example Requests

7.1 Create User

7.2 Get User

7.3 Cancel Task

7.4 Get a Sub-Resource (Issue on a Repo)

7.5 List Sub-Resources (Tasks in a Project)

7.6 Create a Sub-Resource (Message in a Session)

8. Responses

9. Receiver Behavior

9.1 Structured Requests

9.2 Legacy Requests

9.3 Mismatch Handling

9.4 Co-presence Rules

10. Notifications

11. Discovery

12. Authorization Model

13. Transport Independence

14. Implementation Guidance

Preferred Internal Router API

Compatibility Adapter

15. Security Considerations

16. Versioning

17. Rationale

18. Caching

18.1 Cache Directive on Responses

18.2 Cache Directive on Requests

19. Async Results

19.1 Async Result Verbs

19.2 Result Message Structure

19.3 request_id

19.4 Examples

19.5 Status Field

20. Example: AI Agent Usage

21. Example: CLI Usage

Library vs Framework: The Real Difference Between tkucli and clap

clap: a library

What that means in practice

Analogy

tkucli: a framework

What that means in practice

Analogy

The key concept: Inversion of Control

clap

tkucli

Why this matters

Choose clap if you want flexibility

Choose tkucli if you want speed and consistency

Trade-offs

Takeaway

Project

A Different Way to Build Rust CLIs: tkucli vs clap

Two ways to define a CLI

clap (code-first)

tkucli (config-first)

Key differences

What this changes

When each works well

Takeaway

Project

A declarative CLI framework in Rust

🧠 The idea

✨ Example