JSON Schema beans
JsonSchemaAutoConfiguration makes the JSON Schemas of the application beans: one JsonSchemaRegistry that holds them, and an ObjectMapper that uses it to check JSON before it reads a class marked @JsonSchemaSource.
Why
The schemas of an application come from several places: files in lib/resources/, schemas the build downloaded, JsonSchema beans, schemas a client fetches at start. One registry holds them all, so a $ref from one document finds another, the mapper finds the schema of a class, and the actuator can list them.
Example
# lib/resources/application.yml
spring:
json:
schemas:
- location: resources:schemas/order.json
- location: https://example.com/schemas/user.json
sha256: 3f1c...
@Introspected()
@JsonSchemaSource('resources:schemas/order.json')
class Order {
const Order({required this.id});
final String id;
}
@Service()
class Orders {
Orders(this.mapper);
final ObjectMapper mapper;
// Throws a JsonSchemaValidationException listing every violation.
Order parse(String json) => mapper.readValue<Order>(json);
}
Nothing else is needed: the registry has both schemas, and the ObjectMapper bean checks the JSON of Order against its schema first. The build can also write the classes of the schemas in spring.json.schemas (see JSON Schema classes).
The beans
| Bean | Type | Does |
|---|---|---|
jsonSchemaRegistry |
JsonSchemaRegistry |
The registry. Left out when the application declares a JsonSchemaRegistry bean of its own (@ConditionalOnMissingBean) |
jsonSchemaRegistryPostProcessor |
JsonSchemaRegistryPostProcessor |
Runs every JsonSchemaRegistryCustomizer on each JsonSchemaRegistry bean once it is made |
propertiesJsonSchemas |
PropertiesJsonSchemas |
The customizer that adds the schemas the application names |
jsonSchemaMapperCustomizer |
JsonMapperBuilderCustomizer |
Gives the ObjectMapper the registry as its schemaResolver |
What is in the registry
PropertiesJsonSchemas adds, each once:
- the
locationof everyspring.json.schemas[n]; - the
locationof every@JsonSchemaSourceof the application's classes; - every
JsonSchemabean, under its$id(a bean without an$idis skipped with a warning: give itid:or a$idin the document).
A schema is added under its location, because that is what the mapper asks for. A resources: location is read from lib/resources/. A remote one (https://, http://, github:) is read from the copy the build keeps below lib/resources/ (json-schemas/...). When that copy is missing, the start logs a warning that names the build step (dart run build_runner build) and goes on without the schema. A file that is not a schema stops the start and names the location.
# Leave these out of the registry (the app fills it itself).
spring.json.schemas-registry.properties=false
Adding schemas yourself
A JsonSchemaRegistryCustomizer bean fills whichever registry the context has, the application's own too. Customizers run once, when the registry is made, in @Order order:
@Bean()
JsonSchemaRegistryCustomizer partnerSchemas(PartnerClient client) =>
JsonSchemaRegistryCustomizer.of((registry) {
for (final schema in client.schemas()) {
registry.add(schema);
}
});
To use a registry of your own, declare the bean. The auto-configured one backs off, and the customizers still fill yours:
@Bean()
JsonSchemaRegistry registry() => JsonSchemaRegistry();
The ObjectMapper gets the registry as its schemaResolver only when the context has exactly one JsonSchemaRegistry bean. With none or several, the mapper checks nothing.
Properties
| Key | Type | Default | Meaning |
|---|---|---|---|
spring.json.schemas[n].location |
String |
none | resources:schemas/order.json, an https:// or http:// address, or github:owner/repo/path@ref |
spring.json.schemas[n].sha256 |
String |
none | The SHA-256 (hex) of a remote schema. The build refuses another |
spring.json.schemas[n].prefix |
String |
none | What the names of the generated classes start with (Api: ApiOrder) |
spring.json.schemas[n].name |
String |
the schema's title |
The name of the generated root class |
spring.json.schemas-registry.properties |
bool |
true |
false: spring.json.schemas, @JsonSchemaSource and the JsonSchema beans are not added to the registry |
The build reads location, sha256, prefix and name; the application reads location and schemas-registry.properties. See JSON Schema classes.
In Spring (Java)
Spring Boot has no JSON Schema support, so there is nothing to compare with. The pieces are shaped like Spring Boot's own: a customizer bean (like JsonMapperBuilderCustomizer), a registry bean that backs off for your own, and spring.json.* for the keys.