Multi-domain openrpc.json — aggregate at `docs/openrpc.json` + per-domain at `docs/<domain>/openrpc.json` #82

New issue

Closed

opened 2026-05-20 07:10:26 +00:00 by timur · 1 comment

timur commented

2026-05-20 07:10:26 +00:00

Owner

Context

Follow-up from #73 (which moved the spec to docs/openrpc.json). That implementation emits a single file with all domains merged, but per-domain specs are still useful (SDK generation for a single domain, OpenAPI tooling that wants a focused spec, embedded <hero-api-docs> filtered to one domain).

Desired output

When a service has multiple OSchema domains, the generator should produce:

docs/
├── openrpc.json              # aggregation of all domains (current behaviour)
└── <domain>/
    └── openrpc.json          # per-domain spec (new)

For single-domain services the per-domain file is still emitted (no special case).

What to do

Update the generator's OpenRPC emit module (now in crates/generator/src/generate/openrpc.rs after #59) to emit per-domain files in addition to the aggregate.
The aggregate docs/openrpc.json keeps its info.title = service name, methods union all domains.
Per-domain docs/<domain>/openrpc.json has info.title = <service>:<domain> (or similar — pick one in a comment), methods = just that domain.
Update scaffolded _admin template to load whichever spec makes sense (probably the aggregate; per-domain stays a static asset for clients).
Update recipe_server example output. Update hero_service template (one domain — both files should appear).
Update hero_service_scaffold.md skill to document both outputs.

Acceptance

Multi-domain service generates docs/openrpc.json + N × docs/<domain>/openrpc.json.
Single-domain service still gets both files (aggregate + per-domain, even though they're equivalent in that case — keeps the layout uniform).
<hero-api-docs> in scaffolded _admin still resolves.
Existing recipe_server + hero_service rebuild cleanly with the new layout.

#73 — predecessor (single aggregate file).
hero_skills#274 — skill update + template regen rolls into this work (one agent owns the whole cross-repo change).

## Context Follow-up from [#73](https://forge.ourworld.tf/lhumina_code/hero_rpc/issues/73) (which moved the spec to `docs/openrpc.json`). That implementation emits a single file with all domains merged, but per-domain specs are still useful (SDK generation for a single domain, OpenAPI tooling that wants a focused spec, embedded `<hero-api-docs>` filtered to one domain). ## Desired output When a service has multiple OSchema domains, the generator should produce: ``` docs/ ├── openrpc.json # aggregation of all domains (current behaviour) └── <domain>/ └── openrpc.json # per-domain spec (new) ``` For single-domain services the per-domain file is still emitted (no special case). ## What to do - Update the generator's OpenRPC emit module (now in `crates/generator/src/generate/openrpc.rs` after #59) to emit per-domain files in addition to the aggregate. - The aggregate `docs/openrpc.json` keeps its `info.title` = service name, methods union all domains. - Per-domain `docs/<domain>/openrpc.json` has `info.title` = `<service>:<domain>` (or similar — pick one in a comment), methods = just that domain. - Update scaffolded `_admin` template to load whichever spec makes sense (probably the aggregate; per-domain stays a static asset for clients). - Update `recipe_server` example output. Update `hero_service` template (one domain — both files should appear). - Update `hero_service_scaffold.md` skill to document both outputs. ## Acceptance - Multi-domain service generates `docs/openrpc.json` + N × `docs/<domain>/openrpc.json`. - Single-domain service still gets both files (aggregate + per-domain, even though they're equivalent in that case — keeps the layout uniform). - `<hero-api-docs>` in scaffolded `_admin` still resolves. - Existing `recipe_server` + `hero_service` rebuild cleanly with the new layout. ## Related - [#73](https://forge.ourworld.tf/lhumina_code/hero_rpc/issues/73) — predecessor (single aggregate file). - [hero_skills#274](https://forge.ourworld.tf/lhumina_code/hero_skills/issues/274) — skill update + template regen rolls into this work (one agent owns the whole cross-repo change).