JsonApi4j is configured differently depending on your web framework. All three integrations support the same set of properties — only the format and loading mechanism differ.

Configuration by Framework

Spring Boot uses standard application.yaml or application.properties with the jsonapi4j prefix. Properties are bound via @ConfigurationProperties.

application.yaml:

jsonapi4j:
  rootPath: /jsonapi

  validation:
    maxNumberFilterParams: 5
    maxElementsInFilterParam: 20
    resourceIdMaxLength: 64
    limitMaxValue: 100
    maxElementsInIncludeParam: 10
    maxElementsInSortByParam: 5

  ac:
    enabled: true

  sf:
    enabled: true
    requestedFieldsDontExistMode: SPARSE_ALL_FIELDS

  cd:
    enabled: true
    maxHops: 3
    maxIncludedResources: 100
    mapping:
      users: http://localhost:8080/jsonapi
      countries: http://localhost:8080/jsonapi

  oas:
    enabled: true
    info:
      title: My API
      version: 1.0.0

Spring Boot's standard property resolution applies: application.yaml, application.properties, environment variables, system properties, and profile-specific files all work as expected.

All JsonApi4j beans are registered with @ConditionalOnMissingBean, so you can override any bean by defining your own in a @Configuration class.

Quarkus uses application.properties with the same jsonapi4j prefix. Properties are bound at build time via @ConfigMapping.

application.properties:

jsonapi4j.rootPath=/jsonapi

jsonapi4j.validation.maxNumberFilterParams=5
jsonapi4j.validation.maxElementsInFilterParam=20
jsonapi4j.validation.resourceIdMaxLength=64
jsonapi4j.validation.limitMaxValue=100
jsonapi4j.validation.maxElementsInIncludeParam=10
jsonapi4j.validation.maxElementsInSortByParam=5

jsonapi4j.ac.enabled=true

jsonapi4j.sf.enabled=true
jsonapi4j.sf.requestedFieldsDontExistMode=SPARSE_ALL_FIELDS

jsonapi4j.cd.enabled=true
jsonapi4j.cd.maxHops=3
jsonapi4j.cd.maxIncludedResources=100
jsonapi4j.cd.mapping.users=http://localhost:8080/jsonapi
jsonapi4j.cd.mapping.countries=http://localhost:8080/jsonapi

jsonapi4j.oas.enabled=true
jsonapi4j.oas.info.title=My API
jsonapi4j.oas.info.version=1.0.0

Quarkus uses Smallrye Config for property resolution. Lists use indexed syntax: jsonapi4j.cd.propagation[0]=FIELDS. All JsonApi4j CDI beans use @DefaultBean, so you can override them with your own @Produces methods.

For plain Servlet applications, JsonApi4j loads configuration from a YAML or JSON file. No framework-specific property binding is used.

jsonapi4j.yaml (on the classpath):

rootPath: /jsonapi

validation:
  maxNumberFilterParams: 5
  maxElementsInFilterParam: 20
  resourceIdMaxLength: 64
  limitMaxValue: 100
  maxElementsInIncludeParam: 10
  maxElementsInSortByParam: 5

ac:
  enabled: true

sf:
  enabled: true
  requestedFieldsDontExistMode: SPARSE_ALL_FIELDS

cd:
  enabled: true
  maxHops: 3
  maxIncludedResources: 100
  mapping:
    users: http://localhost:8080/jsonapi
    countries: http://localhost:8080/jsonapi

oas:
  enabled: true
  info:
    title: My API
    version: 1.0.0

Note: the Servlet config file uses the property structure directly (no jsonapi4j prefix). Both jsonapi4j.yaml and jsonapi4j.json formats are supported.

Config Loading Order (Servlet)

For Spring Boot and Quarkus, configuration loading follows each framework’s standard rules (profiles, environment variables, system properties, etc.).

For the Servlet integration, JsonApi4j resolves configuration in the following priority order:

Priority Source Example
1 Servlet context attribute Set programmatically or by Spring Boot / Quarkus auto-configuration
2 System property jsonapi4j.config -Djsonapi4j.config=/path/to/config.yaml
3 Environment variable JSONAPI4J_CONFIG export JSONAPI4J_CONFIG=/path/to/config.yaml
4 Servlet init parameter jsonapi4j.config Set in web.xml or programmatically via context.setInitParameter(...)
5 Classpath defaults jsonapi4j.yaml or jsonapi4j.json on the classpath

Core Properties

Property Default Description
jsonapi4j.rootPath /jsonapi Root path for all JsonApi4j endpoints. All resource and relationship URLs are served under this path.

Validation Properties

JsonApi4j includes a built-in structural validator that enforces limits on common request parameters. These properties configure the thresholds used by the built-in validator.

Property Default Description
jsonapi4j.validation.maxNumberFilterParams 5 Maximum number of distinct filter[*] query parameters allowed in a single request.
jsonapi4j.validation.maxElementsInFilterParam 20 Maximum number of comma-separated values within a single filter[name] parameter.
jsonapi4j.validation.resourceIdMaxLength 64 Maximum allowed length of a resource ID string.
jsonapi4j.validation.limitMaxValue 100 Maximum allowed value for the page[limit] pagination parameter.
jsonapi4j.validation.maxElementsInIncludeParam 10 Maximum number of relationship paths in the include query parameter.
jsonapi4j.validation.maxElementsInSortByParam 5 Maximum number of fields in the sort query parameter.

Plugin Properties

Each plugin adds its own properties under the jsonapi4j namespace. Refer to the corresponding plugin page for the full list:

Plugin Prefix Documentation
Access Control jsonapi4j.ac.* Access Control Plugin
Sparse Fieldsets jsonapi4j.sf.* Sparse Fieldsets Plugin
OpenAPI jsonapi4j.oas.* OpenAPI Plugin
Compound Documents jsonapi4j.cd.* Compound Documents Plugin

Overriding Beans

Both Spring Boot and Quarkus allow you to override any default bean provided by JsonApi4j.

Spring Boot — define a bean of the same type in a @Configuration class. JsonApi4j uses @ConditionalOnMissingBean on all defaults.

@Configuration
public class CustomConfig {

    @Bean
    public ExecutorService jsonApi4jExecutorService() {
        return Executors.newVirtualThreadPerTaskExecutor();
    }
}

Quarkus — provide a @Produces method. JsonApi4j beans are annotated with @DefaultBean, so your producer takes precedence.

public class CustomConfig {

    @Produces
    @Singleton
    public ExecutorService jsonApi4jExecutorService() {
        return Executors.newVirtualThreadPerTaskExecutor();
    }
}

Servlet — set custom instances as ServletContext attributes before the framework initializes. JsonApi4j checks the servlet context for known attributes (e.g. JsonApi4j, PrincipalResolver, ErrorHandlerFactoriesRegistry, ExecutorService, ObjectMapper) and uses them if present; otherwise it falls back to defaults.

// Build and register a custom JsonApi4j instance
JsonApi4j jsonApi4j = JsonApi4j.builder()
        .domainRegistry(domainRegistry)
        .operationsRegistry(operationsRegistry)
        .plugins(plugins)
        .executor(Executors.newVirtualThreadPerTaskExecutor())
        .build();
servletContext.setAttribute(JsonApi4jServletContainerInitializer.JSONAPI4J_ATT_NAME, jsonApi4j);

// Override PrincipalResolver
servletContext.setAttribute(JsonApi4jServletContainerInitializer.PRINCIPAL_RESOLVER_ATT_NAME, myCustomPrincipalResolver);

See the servlet sample app for a complete example.

For a complete configuration example with all plugins enabled, see the sample application configs: