jsonapi4j
/jsonapi4j
How to build and reason about JSON:API backends with the jsonapi4j framework (pro.api4) — resources, relationships (to-one/to-many), operations, compound documents/includes, validation, security, config, and RestAssured testing. Use whenever working in a codebase that depends on jsonapi4j (imports under pro.api4.jsonapi4j, @JsonApiResource / @JsonApiRelationship / @JsonApiResourceOperation annotations, a /jsonapi rootPath), or when the user mentions jsonapi4j, JSON:API resources/relationships/compound-docs in such a project.
- Author
- moonworm ↗
- Repository
- jsonapi4j ↗
- Licence
- Apache-2.0
- Last repository change
- 17.10.2026
Assessment and security
- Files in this package
- 11
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 2
No signals detected. Repository changed on 17.10.2026, without references to retired models or APIs.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
What it does and when to use it
How to build and reason about JSON:API backends with the jsonapi4j framework (pro.api4) — resources, relationships (to-one/to-many), operations, compound documents/includes, validation, security, config, and RestAssured testing. Use whenever working in a codebase that depends on jsonapi4j (imports under pro.api4.jsonapi4j, @JsonApiResource / @JsonApiRelationship / @JsonApiResourceOperation annotations, a /jsonapi rootPath), or when the user mentions jsonapi4j, JSON:API resources/relationships/compound-docs in such a project.
Original author description
How to build and reason about JSON:API backends with the jsonapi4j framework (pro.api4) — resources, relationships (to-one/to-many), operations, compound documents/includes, validation, security, config, and RestAssured testing. Use whenever working in a codebase that depends on jsonapi4j (imports under pro.api4.jsonapi4j, @JsonApiResource / @JsonApiRelationship / @JsonApiResourceOperation annotations, a /jsonapi rootPath), or when the user mentions jsonapi4j, JSON:API resources/relationships/compound-docs in such a project.
How it works
- Mental model: the three-part anatomy
- Quick checklist for a new resource
- Reference index — open on demand
SKILL.md preview
---
name: jsonapi4j
description: How to build and reason about JSON:API backends with the jsonapi4j framework (pro.api4) — resources, relationships (to-one/to-many), operations, compound documents/includes, validation, security, config, and RestAssured testing. Use whenever working in a codebase that depends on jsonapi4j (imports under pro.api4.jsonapi4j, @JsonApiResource / @JsonApiRelationship / @JsonApiResourceOperation annotations, a /jsonapi rootPath), or when the user mentions jsonapi4j, JSON:API resources/relationships/compound-docs in such a project.
---
# Working with jsonapi4j
jsonapi4j (`pro.api4`, by Aliaksei Taliuk) is a persistence-agnostic Java framework for building
[JSON:API](https://jsonapi.org/)-compliant REST APIs. No JPA/ORM required — it works over any data
source (JdbcTemplate, a REST client, in-memory, …). It ships **three** integrations: **Spring Boot**,
**Quarkus**, and plain **Jakarta Servlet**. Docs: https://api4.pro/.
This skill is the consumer's guide — how to *build with* the framework. Keep `SKILL.md` lean; open the
matching `reference/<file>.md` when you go deep on a topic (paths below). When you confirm a new pattern
or quirk, add it to the relevant reference file.
**When you write anything down** — a note in `reference/`, the app's README, or an operation
`description` that ships in the published OpenAPI document — document what the *caller* must choose,
know, or watch out for, never what the code does. "Returns a paginated list of users; `page[cursor]`
comes from the previous response's `links.next`" earns its place; "iterates the result set and maps
each row" does not. A rule that fits in a sentence gets a sentence, not a code block.
**Versioned behavior:** edge behaviors are version-specific (current line is 1.11.x). Treat the
"known behaviors" notes as "verify against the version on your classpath and the framework's own
tests," not gospel. The canonical, runnable reference is the framework's `examples/` sample apps
(Spring Boot / Quarkus / Servlet over a shared domain).
## Mental model: the three-part anatomy
Every resource (and every relationship) is split into small single-purpose classes, auto-discovered as
beans (Spring `@Component` / Quarkus CDI / registered in the Servlet context):
1. **`Resource<DTO>`** — maps a backend DTO to a JSON:API resource: `resolveResourceId` +
`resolveAttributes`. Annotated `@JsonApiResource(resourceType = "users")`.
2. **`Relationship<REF>`** — maps to a *resource identifier* (`{type, id}` + optional identifier meta/links).
It has **no attributes**. Annotated
`@JsonApiRelationship(relationshipName = "citizenships", parentResource = UserResource.class)`.
Use `ToOneRelationship<REF>` / `ToManyRelationship<REF>`.
3. **`*Operations`** — the data access. Annotated `@JsonApiResourceOperation(resource = ...)` or
`@JsonApiRelationshipOperation(relationship = ...)`. Implement the composite
`ResourceOperations<DTO>` / `ToOneRelationshipOperations<PARENT, CHILD>` /
`ToManyRelationshipOperations<PARENT, CHILD>` — each method defaults to throwing
`OperationNotFoundException`, so you override only what your resource actually supports, plus the
matching `validateXxx` hooks.
4. **The DTO is deliberately *wider* than the attributes** — it also carries the foreign keys that
relationships need (so relationships can resolve linkage off the parent without extra queries).
```java
@Component
@JsonApiResource(resourceType = "users")
public class UserResource implements Resource<UserDbEntity> {
public String resolveResourceId(UserDbEntity u) { return u.getId(); }
public UserAttributes resolveAttributes(UserDbEntity u) {
return new UserAttributes(u.getFullName(), u.getEmail());
}
}
```
(See the real thing: `examples/jsonapi4j-sampleapp-domain/.../domain/user/UserResource.java`.)
## Quick checklist for a new resource
1. **DTO** (carry FKs for relationships) + `Resource<DTO>` + an `*Attributes` class holding **only this
resource's own data**.
2. **`ResourceOperations<DTO>`**: `readById`, `readPage` (+ `validateReadById` / `validateReadMultiple`);
throw `ResourceNotFoundException` on a miss. Choose a pagination strategy for `readPage`.
3. **Relationships**: `ToOne/ToManyRelationship<Ref>` — **prefer lightweight refs** over heavy DTOs (any
type works; only `id`/`type`/meta are read, so it's your call);
`*Operations` with `readOne`/`readMany` (+ `readOneForResource`/`readManyForResource` and/or batch
ops to avoid N+1 on includes).
4. **Security**: add your web framework's URL-prefix rule if the resource is public; layer the AC plugin
for field-level/ownership gating.
5. **Compound docs**: if the type is includable, support `filter[id]` on its `readPage` (+ a
`jsonapi4j.cd.mapping.<type>.maxBatchSize`). A `cd.mapping.<type>.url` is only for types another
service serves — same-app types are read in-process.
6. **OpenAPI** (if the OAS plugin is on): `@OasResourceInfo(attributes = XAttributes.class)` on the
`Resource` — without it the published schema is empty. Declare `sortableFields` / `filters` on the
operation, or they go undocumented even though they work.
7. **Tests**: RestAssured by-id/filter/404/400 + `?include=` cases (random port is fine; CD profile).
## Reference index — open on demand
- **`reference/resources-and-operations.md`** — Resource contract, the composite operations, pagination
modes and `PaginationAwareResponse` factories (incl. `null` vs `empty()`), the one-mapper-per-resource
data-layer rule.
- **`reference/relationships.md`** — to-one/to-many, lightweight refs vs full DTOs,
`readOneForResource`/`readManyForResource` and batch ops (N+1 avoidance), edge data in identifier meta.
- **`reference/compound-documents.md`** — `?include=`, resolution (in-process for same-app types,
`cd.mapping` over HTTP for cross-service), multi-hop, synthetic-primary caveat, header/param propagation.
- **`reference/performance.md`** — `filter[id]` batching, in-house resolution, parallel `ExecutorService`,
hop/size caps, the compound-docs cache + `Cache-Control`.
- **`reference/validation-and-security.md`** — `validateXxx` hooks, the fluent `JsonApiRequestValidator`,
exceptions (400/404/custom), the two independent security layers + the AC plugin.
- **`reference/configuration.md`** — the `jsonapi4j.*` property reference.
- **`reference/openapi.md`** — the generated OpenAPI document: `@OasResourceInfo` / `@OasOperationInfo`,
which query params are published only when declared, OAuth2 scopes per grant flow, `OasCustomizer`
and the springdoc hand-off.
- **`reference/testing.md`** — RestAssured black-box patterns; `?include=` tests; test profiles;
Testcontainers/Flyway/auth stubs.
- **`reference/separation-of-concerns.md`** — attribute ownership; migrating a denormalized field out to
an `?include`d relationship safely.
- **`reference/known-behaviors.md`** — version-specific quirks (related-URL 404s, to-one linkage
rendering, null refs, cursor meta key, enum attributes, etc.).
Files in this package (11)
- SKILL.md 7 KB
- reference/compound-documents.md 3 KB
- reference/configuration.md 5 KB
- reference/known-behaviors.md 2 KB
- reference/openapi.md 8 KB
- reference/performance.md 3 KB
- reference/relationships.md 8 KB
- reference/resources-and-operations.md 5 KB
- reference/separation-of-concerns.md 2 KB
- reference/testing.md 2 KB
- reference/validation-and-security.md 6 KB
Versions
The database has no other skills named jsonapi4j.
Database snapshot: 13.11.2026 · package version 457cadbe97ac (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100laravel-jsonapi
Use when building JSON:API spec-compliant endpoints in Laravel 13 with the first-party `JsonApiResource` base class. - 100rest-api-test-generator
Generates REST API tests using RestAssured or MockMvc with loop prevention and incremental validation. Triggers on: "test API endpoints", "generate API tests", "test REST API", "create integration tests". - 100restassured-testing
Use whenever Java/JVM API tests need writing or fixing: loose assertions that let an empty 200 pass, slow sequential suites, or hand-rolled HTTP clients. Writes REST Assured given/when/then tests: status, JSON and XML path checks, auth, reusable specs, schema checks, Maven or Gradle and CI reports. - 100quarkus-dev-services-and-testing
Quarkus Dev Services and testing: zero-config containers, @QuarkusTest, @QuarkusIntegrationTest, test resources, RestAssured, @InjectMock, profiles and continuous testing. Use when writing or fixing tests in a Quarkus project. - 95testing-patterns
Testing patterns for Quarkus - @QuarkusTest, RestAssured, Mockito mocking, Dev Services (built-in Testcontainers), and @QuarkusIntegrationTest. Use when user asks about testing, writing tests, test coverage, or test failures. - 100restassured-testing
Strengthens and speeds up JVM API test suites - assertions so loose that an empty `200 OK` passed for three days, a 220-test suite spending fourteen minutes mostly waiting on sequential HTTP calls, or endpoints exercised through a hand-rolled JDK HTTP client with JSON parsed by…