
# 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

```yaml
# lib/resources/application.yml
spring:
  json:
    schemas:
      - location: resources:schemas/order.json
      - location: https://example.com/schemas/user.json
        sha256: 3f1c...
```

```dart
@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](../spring-core-dart-generator/json-schema-classes.md)).

## 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:

1. the `location` of every `spring.json.schemas[n]`;
2. the `location` of every `@JsonSchemaSource` of the application's classes;
3. every `JsonSchema` bean, under its `$id` (a bean without an `$id` is skipped with a warning: give it `id:` or a `$id` in 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.

```properties
# 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:

```dart
@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:

```dart
@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](../spring-core-dart-generator/json-schema-classes.md).

## 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.

## See also

- [JSON Schema](../spring-core-dart/json/json-schema.md)
- [JSON Schema classes](../spring-core-dart-generator/json-schema-classes.md)
- [The jsonschemas endpoint](../spring-boot-actuator/json-schemas.md)
- [Built-in beans](built-in-beans.md)
- [All properties](properties.md)
