Release 1.8.0: Fluent Validation API with Collect-All-Errors

[MoonWorm]

Overview

This release rebuilds the validation system from the ground up. The new fluent API provides a single entry point for validating path segments, query parameters, HTTP headers, and request body — with automatic error source mapping and collect-all-errors behavior.

Previously, validation was fail-fast: one error per round-trip. Now, all configured validators run and every error is returned in a single JSON:API response.

Fluent Validation API

Use JsonApiRequestValidator.forRequest(request) to build validation rules declaratively:

import static pro.api4.jsonapi4j.operation.validation.JsonApiRequestValidator.forRequest;
import static pro.api4.jsonapi4j.operation.validation.ValidationAssertions.*;

@Override
public void validateCreate(JsonApiRequest request) {
    forRequest(request)
            .path(path -> path
                    .withResourceTypeValidator(type -> validateValueAnyOf(type.getType(), Set.of("users"))))
            .singleResourceBody(UserAttributes.class, body -> body
                    .withDataValidator(data -> validateNonNull(data, ErrorSources.pointer().data().toPointer()))
                    .withResourceTypeValidator(type -> validateEqualTo(type, "users"))
                    .withAttributesValidator(att -> {
                        validateNonNull(att, ErrorSources.pointer().data().attributes());
                        validateNonNull(att.getEmail(), ErrorSources.pointer().data().attributes("email"));
                    })
                    .withToManyRelationship("citizenships", this::citizenshipsValidator)
                    .withToOneRelationship("placeOfBirth", this::placeOfBirthValidator))
            .validate();
}

Relationship validators can be extracted as method references for reuse across create and update:

private void citizenshipsValidator(ToManyRelationshipObjectValidationBuilder v) {
    v.withResourceIdValidator(CountryValidator::validateCountryId)
            .withResourceTypeValidator(type -> validateValueAnyOf(type, Set.of("countries")));
}

Automatic Error Source

The builder knows where each validator sits in the request and populates the JSON:API error source field automatically. For example, withResourceIdValidator on a body section maps to "pointer": "/data/id", while the same validator on a path section maps to "path": "{resourceId}". No need to pass ErrorSources manually — just throw, the framework figures out the location.

Collect-All-Errors

When multiple validators fail, the response contains all errors at once:

{
  "errors": [
    {
      "id": "...",
      "status": "400",
      "code": "VALUE_IS_ABSENT",
      "detail": "value can't be null",
      "source": { "pointer": "/data/attributes" }
    },
    {
      "id": "...",
      "status": "400",
      "code": "INVALID_ENUM_VALUE",
      "detail": "'wrong' value is not allowed, available values: [countries]",
      "source": { "pointer": "/data/relationships/citizenships/data/0/type" }
    }
  ]
}

Each developer-provided lambda is atomic — fail-fast within a lambda, collect-all across lambdas. This prevents NPEs from interdependent checks while collecting errors across independent validators.

Framework-Internal Validation Rebuilt

The built-in structural validator (DefaultJsonApiBuildInRequestValidator) — responsible for resource type checks, ID length, filter/sort/include limits, and payload structure — was rewritten to use the same forRequest() API. One validation model for both framework internals and developer code.

HTTP Headers on Request

JsonApiRequest now carries HTTP headers via HeadersAwareRequest. Validate them alongside path and query parameters using the same builder:

.headers(headers -> headers
        .withHeaderValidator("X-Tenant-Id", tenantId -> validateNonBlank(tenantId)))

Other Changes

• Compound Docs batch fetching — The resolver now splits large filter[id] requests into configurable per-resource-type chunks, fetched in parallel. Only cache misses are fetched. Configure via jsonapi4j.cd.defaultMaxBatchSize and jsonapi4j.cd.batchSizeMapping.
• Startup banner — JsonApi4j now prints its logo on startup alongside the state report.

Resources

• Documentation: https://api4.pro/
• Validation docs: https://api4.pro/validation/
• Release notes: https://github.com/MoonWorm/jsonapi4j/releases/tag/v1.8.0