Skip to content
Skills Library
Programming · Building & coding

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.

Repository
jsonapi4j ↗
Licence
Apache-2.0
Last repository change
17.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
11
Scripts
0
HTML comments
0
URLs in SKILL.md
2
Deprecation

No signals detected. Repository changed on 17.10.2026, without references to retired models or APIs.

Licence

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

  1. Mental model: the three-part anatomy
  2. Quick checklist for a new resource
  3. Reference index — open on demand
Original SKILL.md headings · 100 lines, 773 words
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…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.