Rayfold 0.1 overview
Rayfold is an API protocol where the rules live in the schema: the shape of a request, who may make it, what may be cached, how a client's state stays true, and what may change later. 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 |
| 04 §9 | Uploads | Extension upload |
| 06 §6 | Capability tokens | Extension cap |
| 11 | Evolution | Core (tooling) |
| 12 | Security | Core |
| 13 | Patches and client state | 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 three kinds of operation: query (safe, cacheable, shapeable, may be live), command (state-changing, idempotency key required, typed errors, returns a result and cache patches) and stream (a sequence of typed items). It also declares event types, published facts a stream can deliver. 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; patches, caches and ETags are keyed on it. 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. Any implementation in any language must get this layer right, and the conformance fixtures check it. - 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.
Compared with GraphQL, REST and gRPC
See docs/comparison.md for the feature matrix and benchmark results and docs/landscape.md for the 2026 state of each incumbent. Each of them wins one dimension. In Rayfold 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 would be per extension directory; none is published yet, so core/ is the whole suite today. See conformance/README.md.