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 は、次のものを一度ずつ追加します。

  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 を示します。

# これらをレジストリに入れない (アプリケーションが自分で満たす)。
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.* です。

関連項目