mirror of
https://github.com/zap-proto/zap-spec.git
synced 2026-10-30 15:02:53 +00:00
1.4 KiB
1.4 KiB
zap-proto/zap-spec
What this is
The canonical, language-agnostic schema layer for the ZAP wire format.
Schema-only — no compilable code lives here. The Go runtime
(github.com/zap-proto/go), the TypeScript runtime (zap-es), and any
future runtimes consume these .zap files via their own codegen.
When to add files here
Any new ZAP message family lands here first, before any runtime adds helpers for it. The flow is:
- Author
<family>.zap+<family>_kinds.mdin this repo. - Tag this repo (e.g.
v1.1.0). - Each runtime pins to the tag and emits codegen.
- Downstream services consume the runtime's typed accessors.
What does NOT live here
- Compilable Go / TS / Rust code.
- Codegen binaries (those live in each runtime's
cmd/zapgen*). - Service-specific message types (those belong in the service repo using
a
package <service>declaration, generated by codegen).
Wire stability
Once a .zap file ships in a tagged release it is frozen. New fields
go in a sibling struct with a new name + new ShapeKind byte. No optional
fields, no version negotiation. This is a deliberate choice — ZAP's
fixed-offset reads require that bytes mean exactly one thing.
Cross-reference
- Wire format primitives and DSL grammar:
README.md - Capability semantics, threat model, revocation rules:
SPEC.md - DSL parser source of truth:
github.com/zap-proto/go/cmd/zapgen/parser.go