JSON Schema の Bean
JsonSchemaAutoConfiguration は、アプリケーションの JSON Schema を Bean にします。スキーマを保持する一つの JsonSchemaRegistry と、@JsonSchemaSource を付けたクラスを読む前に、それを使って JSON を検査する ObjectMapper です。
使う理由
アプリケーションのスキーマは複数の場所から来ます。lib/resources/ のファイル、ビルドがダウンロードしたスキーマ、JsonSchema の Bean、クライアントが起動時に取得するスキーマなどです。一つのレジストリがそれらをすべて保持するので、ある文書の $ref は別の文書を見つけ、マッパーはクラスのスキーマを見つけ、Actuator はそれらを列挙できます。
例
# 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;
// すべての違反を列挙した JsonSchemaValidationException を投げる。
Order parse(String json) => mapper.readValue<Order>(json);
}
ほかに必要なものはありません。レジストリは両方のスキーマを持ち、ObjectMapper の Bean は Order の JSON を先にそのスキーマに照らして検査します。ビルドは spring.json.schemas のスキーマのクラスを書き出すこともできます (JSON Schema のクラス を参照)。
Bean
| Bean | 型 | 動作 |
|---|---|---|
jsonSchemaRegistry |
JsonSchemaRegistry |
レジストリ。アプリケーションが独自の JsonSchemaRegistry の Bean を宣言すると外れます (@ConditionalOnMissingBean) |
jsonSchemaRegistryPostProcessor |
JsonSchemaRegistryPostProcessor |
各 JsonSchemaRegistry の Bean が作られると、すべての JsonSchemaRegistryCustomizer を実行します |
propertiesJsonSchemas |
PropertiesJsonSchemas |
アプリケーションが指すスキーマを追加するカスタマイザー |
jsonSchemaMapperCustomizer |
JsonMapperBuilderCustomizer |
ObjectMapper に、レジストリを schemaResolver として渡します |
レジストリに入るもの
PropertiesJsonSchemas は、次のものを一度ずつ追加します。
- すべての
spring.json.schemas[n]のlocation。 - アプリケーションのクラスのすべての
@JsonSchemaSourceのlocation。 - すべての
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 を示します。
# これらをレジストリに入れない (アプリケーションが自分で満たす)。
spring.json.schemas-registry.properties=false
スキーマを自分で追加する
JsonSchemaRegistryCustomizer の Bean は、コンテキストにあるレジストリ (アプリケーション独自のものも) を満たします。カスタマイザーは、レジストリが作られるときに一度だけ、@Order の順に実行されます。
@Bean()
JsonSchemaRegistryCustomizer partnerSchemas(PartnerClient client) =>
JsonSchemaRegistryCustomizer.of((registry) {
for (final schema in client.schemas()) {
registry.add(schema);
}
});
独自のレジストリを使うには、その Bean を宣言します。自動構成のものは外れ、カスタマイザーは独自のものを満たします。
@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 (Java) との対応
Spring Boot には JSON Schema のサポートがないため、比べるものはありません。部品の形は Spring Boot 自身のものに倣っています。カスタマイザーの Bean (JsonMapperBuilderCustomizer と同様)、独自のものがあると外れるレジストリの Bean、キーの spring.json.* です。