
# JSON Schema の Bean

`JsonSchemaAutoConfiguration` は、アプリケーションの JSON Schema を Bean にします。スキーマを保持する一つの `JsonSchemaRegistry` と、`@JsonSchemaSource` を付けたクラスを読む前に、それを使って JSON を検査する `ObjectMapper` です。

## 使う理由

アプリケーションのスキーマは複数の場所から来ます。`lib/resources/` のファイル、ビルドがダウンロードしたスキーマ、`JsonSchema` の Bean、クライアントが起動時に取得するスキーマなどです。一つのレジストリがそれらをすべて保持するので、ある文書の `$ref` は別の文書を見つけ、マッパーはクラスのスキーマを見つけ、Actuator はそれらを列挙できます。

## 例

```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;

  // すべての違反を列挙した JsonSchemaValidationException を投げる。
  Order parse(String json) => mapper.readValue<Order>(json);
}
```

ほかに必要なものはありません。レジストリは両方のスキーマを持ち、`ObjectMapper` の Bean は `Order` の JSON を先にそのスキーマに照らして検査します。ビルドは `spring.json.schemas` のスキーマのクラスを書き出すこともできます ([JSON Schema のクラス](../spring-core-dart-generator/json-schema-classes.md) を参照)。

## Bean

| Bean | 型 | 動作 |
|---|---|---|
| `jsonSchemaRegistry` | `JsonSchemaRegistry` | レジストリ。アプリケーションが独自の `JsonSchemaRegistry` の Bean を宣言すると外れます (`@ConditionalOnMissingBean`) |
| `jsonSchemaRegistryPostProcessor` | `JsonSchemaRegistryPostProcessor` | 各 `JsonSchemaRegistry` の Bean が作られると、すべての `JsonSchemaRegistryCustomizer` を実行します |
| `propertiesJsonSchemas` | `PropertiesJsonSchemas` | アプリケーションが指すスキーマを追加するカスタマイザー |
| `jsonSchemaMapperCustomizer` | `JsonMapperBuilderCustomizer` | `ObjectMapper` に、レジストリを `schemaResolver` として渡します |

## レジストリに入るもの

`PropertiesJsonSchemas` は、次のものを一度ずつ追加します。

1. すべての `spring.json.schemas[n]` の `location`。
2. アプリケーションのクラスのすべての `@JsonSchemaSource` の `location`。
3. すべての `JsonSchema` の Bean。`$id` をキーにします (`$id` のない Bean は警告してスキップされます。`id:` か、文書の `$id` を付けてください)。

スキーマは、マッパーが尋ねるのが location なので、location をキーにして追加されます。`resources:` の location は `lib/resources/` から読まれます。リモートのもの (`https://`、`http://`、`github:`) は、ビルドが `lib/resources/` の下 (`json-schemas/...`) に保存したコピーから読まれます。そのコピーがないと、起動時にビルドの手順 (`dart run build_runner build`) を示す警告をログに出し、そのスキーマなしで続けます。スキーマではないファイルは起動を止め、location を示します。

```properties
# これらをレジストリに入れない (アプリケーションが自分で満たす)。
spring.json.schemas-registry.properties=false
```

## スキーマを自分で追加する

`JsonSchemaRegistryCustomizer` の Bean は、コンテキストにあるレジストリ (アプリケーション独自のものも) を満たします。カスタマイザーは、レジストリが作られるときに一度だけ、`@Order` の順に実行されます。

```dart
@Bean()
JsonSchemaRegistryCustomizer partnerSchemas(PartnerClient client) =>
    JsonSchemaRegistryCustomizer.of((registry) {
      for (final schema in client.schemas()) {
        registry.add(schema);
      }
    });
```

独自のレジストリを使うには、その Bean を宣言します。自動構成のものは外れ、カスタマイザーは独自のものを満たします。

```dart
@Bean()
JsonSchemaRegistry registry() => JsonSchemaRegistry();
```

`ObjectMapper` がレジストリを `schemaResolver` として受け取るのは、コンテキストに `JsonSchemaRegistry` の Bean がちょうど一つあるときだけです。ないときや複数あるときは、マッパーは何も検査しません。

## プロパティ

| キー | 型 | デフォルト | 意味 |
|---|---|---|---|
| `spring.json.schemas[n].location` | `String` | なし | `resources:schemas/order.json`、`https://` または `http://` のアドレス、`github:owner/repo/path@ref` |
| `spring.json.schemas[n].sha256` | `String` | なし | リモートのスキーマの SHA-256 (十六進)。ビルドは別のものを拒否します |
| `spring.json.schemas[n].prefix` | `String` | なし | 生成されるクラスの名前の先頭に付くもの (`Api`: `ApiOrder`) |
| `spring.json.schemas[n].name` | `String` | スキーマの `title` | 生成されるルートクラスの名前 |
| `spring.json.schemas-registry.properties` | `bool` | `true` | `false`: `spring.json.schemas`、`@JsonSchemaSource`、`JsonSchema` の Bean をレジストリに追加しない |

ビルドは `location`、`sha256`、`prefix`、`name` を読み、アプリケーションは `location` と `schemas-registry.properties` を読みます。[JSON Schema のクラス](../spring-core-dart-generator/json-schema-classes.md) を参照してください。

## Spring (Java) との対応

Spring Boot には JSON Schema のサポートがないため、比べるものはありません。部品の形は Spring Boot 自身のものに倣っています。カスタマイザーの Bean (`JsonMapperBuilderCustomizer` と同様)、独自のものがあると外れるレジストリの Bean、キーの `spring.json.*` です。

## 関連項目

- [JSON Schema](../spring-core-dart/json/json-schema.md)
- [JSON Schema のクラス](../spring-core-dart-generator/json-schema-classes.md)
- [jsonschemas エンドポイント](../spring-boot-actuator/json-schemas.md)
- [組み込みの Bean](built-in-beans.md)
- [すべてのプロパティ](properties.md)
