Rayfold 0.1 overview
Rayfold is an application protocol for typed, client-shaped, streaming, cache-coherent APIs. This document is the entry point; the numbered documents are normative.
| # | Document | Profile |
|---|---|---|
| 01 | Schema | Core |
| 02 | Shapes | Core |
| 03 | Batches and pipelining | Core |
| 04 | Frames and transport | Core |
| 05 | Errors | Core |
| 06 | Authorization | Core |
| 07 | Caching | Core |
| 08 | Live queries and sync | Extension live |
| 09 | Binary format (RB) | Extension rb |
| 10 | MCP bridge | Extension mcp |
| 04 §8 | HTTP bindings and OpenAPI | Extension http |
| 11 | Evolution | Core (tooling) |
| 12 | Security | Core |
The key words MUST, MUST NOT, SHOULD and MAY are used as in RFC 2119.
Status. Core 0.1 is frozen with the first release: it changes only by errata and clarifications. The extensions are drafts. process.md says what may change in each part and how changes are proposed.
Model in one paragraph
A schema declares types and four kinds of operation: query (safe, cacheable, shapeable, may be live), command (state-changing, idempotency key required, typed errors, returns a result and cache patches), stream (a sequence of typed items with backpressure) and event (a published fact that can be subscribed to and replayed). A client sends a batch of operations; later operations may reference results of earlier ones. The server answers with a stream of frames, one or more per operation, on any transport that can carry ordered chunks. Every entity has a global identity Type:id, which is what patches, caches and ETags are keyed on. JSON and the binary RB format encode the same model; a server MUST support JSON.
Protocol, schema language, libraries
Rayfold has three layers, and only the first two are normative.
- The protocol: the batch envelope, frames, error codes with their
retryablehint, idempotency keys and what a server promises about a repeated key, and how@cachebecomes HTTP caching headers. This is what any implementation in any language must get right, and what the conformance fixtures check. - The schema language: types, operations and the rules written next to them (policies, cost, cache lifetimes, declared errors, deprecation). Every implementation enforces the same rules for the same schema.
- The reference libraries:
@rayfold/server,@rayfold/client,@rayfold/reactand the JVM modules. Their designs, such as batch loaders, a normalized client cache, React hooks, optimistic updates and an offline queue, are one way to build on the protocol. A client that sends a batch and reads the frames, a curl script included, is as much a Rayfold client as they are.
Why not just GraphQL / REST / gRPC
See docs/comparison.md for the feature matrix and benchmark results and docs/landscape.md for the 2026 state of each incumbent. The short version: each of them wins one dimension. Rayfold is designed so that the mechanisms compose: persisted shapes make client-shaped queries CDN-cacheable; batch-by-default loaders make client-shaped queries safe from N+1; typed error unions and patches make commands composable; schema-level policy makes all of the above enforceable before deployment.
Conformance
An implementation is Core-conformant when it passes every fixture in conformance/fixtures/core/. Extension conformance is per extension directory. See conformance/README.md.