ash-jsonapi
Disclaimer: this repository contains AI-generated code.
Describe a resource once, and get the wire format for free: the type/id
envelope, relationship linkage, self/related links, spec-shaped errors with
JSON Pointers, and request-body validation.
resource!
api!
That is GET|POST /todos and GET /todos/{id}, serialized to spec, with
bodies checked against a JSON Schema derived from the declaration. routes()
is an ordinary axum::Router<App> — mount it wherever the rest of your service
lives.
Status: pre-v1. The API is still moving; expect breaking changes between minor versions until 1.0.
What you write
Two macros, and they are independent — either can be replaced by the traits it stands for.
resource!writes the wire format: the schema, the request-body type and its parsing, the serialization, and the JSON Schema bodies are validated against.api!writes the routes. Name the operations you want fromLIST,CREATE,READ,UPDATE,DELETE,CONTENT,STREAM,INGEST— orCRUDfor the first five. Only the operations you route require their traits, so a read-only service implementsReadand nothing else.
Storage is one trait per operation (Create, Read, List, Update,
Delete), implemented against your own state. There is no ORM here and no
database opinion: the crate owns the wire format, you own the data.
One layer is not optional — ash_jsonapi::layer() attaches the per-request
Context carrying the correlation id and principal. Without it every request
is a 500.
Features
| Feature | Default | What it adds |
|---|---|---|
http |
yes | The axum integration: api!, the response types |
validation |
yes | DocumentValidator — request bodies vs. a JSON Schema |
audit |
yes | audit::Audit — one recorded event per operation |
domain |
no | ash-domain integration |
streaming |
no | JSONL in and out: the STREAM and INGEST operations |
That is the whole list. TLS, health, metrics, OpenTelemetry, OpenAPI and idempotency are planned rather than shipped, and are deliberately not declared as features until they gate real code — a feature that compiles and does nothing is worse than one that is absent.
audit is on by default rather than opt-in: a REST service that does not
record its authorization decisions is a liability. Registering the hook is
still yours, because where the records go is a deployment decision this crate
should not make.
Standalone
With default-features = false you get the document, error and serialization
types alone — no axum, no async runtime, and no ash-* crate in the tree at
all. Implement Schema and RelationshipDef over your own types and those
layers work unchanged.
This is exercised rather than merely claimed: the wire-type tests carry no
required-features and make test-bare runs the suite that way.
Using ash-domain
Optional, and off by default. Enable domain and domain_resource! writes the
same traits from the schema the domain already holds — no attribute, type or
relationship restated. Actions run through the domain's own pipeline, so
policies and extensions apply and a denial reaches the client as a 403.
The integration is a second way in, not the way in.
Beyond CRUD
- Files —
Uploadin,Downloadout, and aCONTENToperation routing/{id}/content. - JSONL (
streaming) — one resource per line for collections too large to be a document.STREAMsends them, selected byAccept;INGESTreads them, answering one result line per input line so a partial batch is visible rather than guessed at. - Hooks —
before/afteraround every operation; what audit, and later metrics, are built on. - i18n — translation keys on errors, and a negotiated
Locale.
Installation
# with the ash-domain integration
Examples
Both are standalone — no domain feature — which is what they exist to
demonstrate.
Development
The feature matrix is the thing most likely to break silently, so make features compiles the library under each feature set individually, and make test-bare builds and runs the tests with no features at all.
Minimum supported Rust version
1.88, and the edition is 2024. This is a floor, not a pin: raising it is a
minor-version change, and the toolchains CI job is what keeps the declared version
honest rather than aspirational.
Contributing
See CONTRIBUTING.md. To report a security issue, see SECURITY.md.
License
Licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)
at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.