Vidocq Documentation
Version

Consolidated reference for the Maven artifacts, Java modules, supported annotations, JsonbConfig properties, and runtime configuration points of Champollion.

Maven artifacts

groupId:artifactId Role

io.vidocq.champollion:champollion-api

Pure re-exposition of the Jakarta specs (jakarta.json, jakarta.json.bind). Useful for consumer modules that don’t want to depend on an implementation.

io.vidocq.champollion:champollion-jsonp

JSON-P 2.1 implementation (parser, generator, object model, Patch / Pointer / Merge Patch). JsonProvider ServiceLoader.

io.vidocq.champollion:champollion-jsonb

JSON-B 3.0 implementation (Jsonb, JsonbBuilder, JsonbConfig). Depends on champollion-jsonp.

io.vidocq.champollion:champollion-codegen-apt

Annotation Processor (scope provided) generating JsonbBinding<T> at compile time.

io.vidocq.champollion:champollion-codegen-maven-plugin

champollion:generate Mojo bound to generate-sources; generates bindings for the record FQNs listed explicitly in <targets> (no classpath scanning) — for types you cannot annotate yourself.

io.vidocq.champollion:champollion-bench

JMH — Parsson/Yasson/Jackson comparisons. No runtime scope.

io.vidocq.champollion:champollion-examples

Runnable examples.

io.vidocq.champollion:champollion-tck (in-reactor, tck Maven profile)

Official TCK runner JSON-P 2.1 + JSON-B 3.0. Joins the reactor only under -Ptck; invoke through run-official-tck-*.sh (see TCK Jakarta JSON-P 2.1 + JSON-B 3.0).

Java modules

Module Public exports SPI / provides

io.vidocq.champollion.api

io.vidocq.champollion.spi (stable public SPI, e.g. RawJsonKeyWriter); requires transitive jakarta.json and jakarta.json.bind

—

io.vidocq.champollion.jsonp

No public exports (one qualified export: io.vidocq.champollion.jsonp.internal to io.vidocq.champollion.jsonb only, for the P9 parser pool)

provides jakarta.json.spi.JsonProvider with io.vidocq.champollion.jsonp.internal.ChampollionJsonProvider

io.vidocq.champollion.jsonb

io.vidocq.champollion.jsonb.spi (JsonbBinding, @JsonbStatic, PrimedJsonParser)

provides jakarta.json.bind.spi.JsonbProvider with io.vidocq.champollion.jsonb.internal.ChampollionJsonbProvider; uses io.vidocq.champollion.jsonb.spi.JsonbBinding

io.vidocq.champollion.codegen.apt

—

provides javax.annotation.processing.Processor with io.vidocq.champollion.codegen.apt.JsonbStaticProcessor

Internal packages (*.internal) are not exported — do not depend on them, they may break between versions. The provider classes above live in internal packages on purpose: they are reached through ServiceLoader, never referenced directly.

Supported JSON-B annotations

Standard Jakarta JSON Binding 3.0 annotations — all supported:

Annotation Effect

@JsonbProperty("name")

Renames the JSON property. On a constructor parameter: used for resolution.

@JsonbTransient

Excludes the property (read and write).

@JsonbDateFormat("yyyy-MM-dd")

Date / time format. Applies to java.time.*, java.util.Date, Calendar.

@JsonbNumberFormat(",#0.00")

Numeric format (cf. DecimalFormat).

@JsonbTypeAdapter(MyAdapter.class)

Adapter on a property or class.

@JsonbTypeSerializer(MySer.class) / @JsonbTypeDeserializer(…​)

Custom serializer / deserializer.

@JsonbVisibility(MyStrategy.class)

Visibility strategy (fields vs accessors).

@JsonbCreator

Constructor or factory used for deserialization. Records natively supported without annotation.

@JsonbNillable

Forces writing of null for this property (or class).

@JsonbPropertyOrder({"a", "b", "c"})

Property write order.

@JsonbTypeInfo + @JsonbSubtype

Polymorphism with discriminator (new in JSON-B 3.0).

Champollion-specific annotations:

@JsonbStatic (io.vidocq.champollion.jsonb.spi)

Marks a record for binding generation by champollion-codegen-apt. It is the APT’s only trigger — types carrying just @JsonbProperty etc. stay on the runtime introspection path.

JsonbConfig properties

All standard jakarta.json.bind.JsonbConfig properties are supported (cf. https://jakarta.ee/specifications/jsonb/3.0/):

Property Description

JSONB_FORMATTING (withFormatting)

Pretty-print with indentation.

JSONB_NULL_VALUES (withNullValues)

Include null properties in the output.

JSONB_LOCALE (withLocale)

Locale for date / number formats.

JSONB_DATE_FORMAT (withDateFormat)

Global date / time format.

JSONB_PROPERTY_NAMING_STRATEGY

IDENTITY, LOWER_CASE_WITH_DASHES, LOWER_CASE_WITH_UNDERSCORES, UPPER_CAMEL_CASE, CASE_INSENSITIVE…​

JSONB_PROPERTY_ORDER_STRATEGY

LEXICOGRAPHICAL, ANY, REVERSE.

JSONB_BINARY_DATA_STRATEGY

BYTE, BASE_64, BASE_64_URL.

JSONB_ENCODING

UTF-8 by default.

withAdapters(…​), withSerializers(…​), withDeserializers(…​)

Global registration.

There are no Champollion-specific configuration properties — configuration is the standard JsonbConfig surface only. Static bindings are discovered automatically via ServiceLoader (META-INF/services/io.vidocq.champollion.jsonb.spi.JsonbBinding); to audit which types are statically bound, inspect that services file in the produced jar.

JsonProvider & JsonbProvider

Auto-discovered via ServiceLoader:

  • META-INF/services/jakarta.json.spi.JsonProvider → io.vidocq.champollion.jsonp.internal.ChampollionJsonProvider

  • META-INF/services/jakarta.json.bind.spi.JsonbProvider → io.vidocq.champollion.jsonb.internal.ChampollionJsonbProvider

To force the implementation (multi-impl on the classpath) — JSON-P defines a system property; JSON-B is selected programmatically:

-Djakarta.json.provider=io.vidocq.champollion.jsonp.internal.ChampollionJsonProvider
Jsonb jsonb = JsonbBuilder.newBuilder(
        "io.vidocq.champollion.jsonb.internal.ChampollionJsonbProvider").build();

Other containers NEW

Champollion does not depend on CDI or on Vauban. When a CDI container runs, it resolves JSON-B adapters, serializers and deserializers through CDI.current() first, as JSON-B 3.0 §5 requires, and falls back to their no-arg constructor otherwise. Two integration-test modules, grouped under champollion-it-other-containers, prove it on every build (champollion#19):

Module What it runs

champollion-it-weld

Weld SE 6.0 (CDI 4.1), class path, no Vauban: JsonProvider.provider() and JsonbBuilder.create() answer with Champollion, and a @JsonbTypeAdapter adapter is a CDI bean with an injected field, in both directions.

champollion-it-openliberty

A WAR bundling champollion-jsonb on Open Liberty 26.0.0.10, MicroProfile 7 distribution (CDI 4.0, Jakarta REST 3.1): the same checks, over HTTP.

Neither module is published.

Deploying on an application server

  • Keep the server’s JSON-B off — jsonb-3.0 on Open Liberty. With it, JsonbBuilder.create() answers with the server’s provider (Yasson), not with the Champollion the application bundles; champollion-it-openliberty catches it. The server’s JSON-P (jsonp-2.1, which restfulWS-3.1 brings) is harmless: JsonProvider.provider() still answers with Champollion. Open Liberty’s "bring your own provider" features, jsonpContainer-2.1 and jsonbContainer-3.0, are not part of the MicroProfile 7 distribution.

  • Without the server’s JSON-B, Jakarta REST does not map JSON entities — read and write the body with Jsonb yourself, or register a MessageBodyReader/MessageBodyWriter that does.

  • Nothing to exclude — the WAR carries champollion-jsonb, champollion-jsonp, champollion-api and the JSON-P and JSON-B API jars; with jsonb-3.0 off, the application’s copies are used. champollion-it-openliberty builds its WAR with exactly these dependencies.

champollion-codegen-maven-plugin Maven plugin

<plugin>
  <groupId>io.vidocq.champollion</groupId>
  <artifactId>champollion-codegen-maven-plugin</artifactId>
  <version>${champollion.version}</version>
  <executions>
    <execution>
      <goals><goal>generate</goal></goals>
    </execution>
  </executions>
  <configuration>
    <targets>
      <target>com.acme.dto.Order</target>
      <target>com.acme.dto.Customer</target>
    </targets>
  </configuration>
</plugin>

Bound to generate-sources. <targets> takes explicit record FQNs (present on the compile classpath) — there is no package scanning, no wildcards, no excludes. For each target the Mojo emits a <FQN>$$Trigger.java annotated @JsonbStatic and runs javac with JsonbStaticProcessor — 100% delegation to champollion-codegen-apt, no duplicated generation logic. Generated sources land in target/generated-sources/champollion (added to the compile source roots). If your types are annotated @JsonbStatic directly, you do not need this plugin: the APT runs during normal compilation.

Compatibility

Resources