2019年9月 リリースノート

ほとんどのスキーマ作成者にとって、これらの変更は最小限の影響しかないことを願っています。

最も不満を招きやすいのは、formatがデフォルトでは検証アサーションとして扱われなくなったことです（ただし、アプリケーションまたはユーザーが検証ツールを構成してアサーションとして扱うようにすることは依然として可能です）。多くのスキーマ作成者がその一貫性のない動作にすでに非常に不満を抱いているため、これは許容できる変更だと判断しました。

実装者にとっては、考慮すべき点がはるかに多く、実装に関するさらなるガイダンスは近日中に提供されます。

• 非互換の変更
• 準非互換の変更
• アノテーション、エラー、および出力
• キーワードの変更
  • コアボキャブラリ
  • 適用ボキャブラリ
  • 検証ボキャブラリ
  • フォーマットボキャブラリ
  • コンテンツボキャブラリ
  • メタデータボキャブラリ
  • ハイパー スキーマボキャブラリ

各ドキュメントへの変更の基本的なリストについては、変更ログを参照してください。

• コア
• 検証
• ハイパー スキーマ

非互換の変更

• デフォルトでは、formatはアサーションではなくなりました。これは、アサーションとしてのformat の実装の矛盾が、スキーマ作成者にとって驚くべき問題の絶え間ない原因となっていたためです。デフォルトの動作は、理想的ではないにしても、予測可能になります。以下で説明するように、アサーション機能を有効にする方法はいくつかあります。ただし、アプリケーション層でセマンティック検証を行うことをお勧めします。
• プレーンな名前フラグメントは、$idではなく、新しいキーワード$anchor（構文が異なります）で定義されるようになりました。
• $idは、フラグメントを含められなくなりました（空のフラグメントは除きますが、推奨されません）。
• 同じスキーマに複数のURIを使用できる場合、一部は推奨されなくなりました。これは、関連する動作がかなり混乱していて、draft-07（draft-handrews-json-schema-01）の更新版まで十分に説明されていなかったため、めったに使用されていなかったと考えられています。これが意味不明な場合は、おそらく安全です。

準非互換の変更

これらのキーワードの古い構文はエラーではありません（デフォルトのメタスキーマは依然としてそれらを検証します）。したがって、実装は互換性モードを提供できます。ただし、新しいキーワードへの移行は簡単であり、優先されるべきです。

• definitionsは、$defsになりました。
• dependenciesはdependentSchemasとdependentRequiredに分割されました。

アノテーション、エラー、および出力

アノテーションキーワード（title、readOnly、defaultなど）は常にJSONスキーマの一部でしたが、それらを利用する方法に関するガイダンスはありませんでした。このドラフトでは、実装がどのようにアノテーション情報をアプリケーションで使用できるようにするかを正式に規定しています。

同様に、検証が失敗した場合に役立つエラーレポートの構成に関するガイダンスもこれまでありませんでした。

これらの両方の問題を解決するために、実装では、標準化された出力形式の1つ以上をサポートすることをお勧めします。

キーワードの変更

すべてのキーワードは、ボキャブラリに整理され、コアと検証の仕様には複数のボキャブラリが含まれています。このプロセスでは、一部のキーワードが検証からコアに移動されました。

コアボキャブラリ

コア仕様、セクション8

適用ボキャブラリ

コア仕様、9節

これらのキーワードは、以前は検証仕様にありました。

他の適用子語彙キーワードは、items、additionalItems、properties、patternProperties、additionalProperties、anyOf、allOf、oneOf、not、if、then、elseです。

検証ボキャブラリ

検証仕様、6節

フォーマットボキャブラリ

検証仕様、7節

formatキーワードは、そのオプションの性質のために常に問題がありました。実装がスキーマを処理する際にformatを全くサポートしているかどうか、またはサポートしている場合、どの程度各タイプの形式を検証するのかを確実に確認する方法がありませんでした。理論的には、各形式は標準仕様を参照しているので、形式がサポートされている場合、一貫して動作するはずです。実際には、そうではありません。

アプリケーションが形式を検証するには2つの方法があります。JSON Schemaの実装に依存して検証させる（予期せぬ結果になる可能性があります）、またはformatキーワードが使用されている場所に注意し、それに基づいて独自の検証を実行することです。この2番目のアプローチは、formatをアノテーションキーワードとして扱い、基本、詳細、または冗長な出力形式をサポートすることによってサポートされています。

このシステムに予測可能性を課すために、以下に示すように、動作がいくつかの点で変更されました。format検証は、デフォルトでは予測可能にオフになっていますが、オンになるように構成できます。ドラフト-07では、デフォルトでオン（ただし実装されていない可能性があります）で、オフになるように構成できました。

次の表で、「サポート済み」列は、実装がformatキーワードをサポートしているかどうか（および2019-09の場合、どの程度サポートしているか）を示しています。「構成」列は、formatのデフォルト以外の動作が何らかの方法で構成されているかどうか（構成ファイル、コマンドラインオプション、その他）を示しています。

ドラフト-07の動作の概要

明らかに、各実装はスキーマ間で一貫して動作しますが、仕様の表現にもかかわらず、一部の形式は他の形式よりも徹底的にサポートされている可能性があります。しかし、実際には、複雑な形式は、各実装で異なる程度にサポートされています。そもそもサポートされている場合。

2019-09の動作の概要

このドラフトの目標は、デフォルトの動作を予測可能にし、一貫性のない動作をオプトイン機能にすることです。これは完全に満足できるものではありませんが、驚くべき結果に関する苦情の数を減らすための良い第一歩であると考えています。こうすることで、少なくともサプライズは減るはずです。

• 「ベストエフォート」検証は、今日の実際の動作と一致する、かなり弱い要件です。単純な形式はおそらく完全に有効であり、複雑な形式は最小限に検証されるか、まったく検証されない可能性があります。

• 「完全な構文」検証とは、実装言語で一般的に使用可能なライブラリが実行できるものに対応する、合理的に徹底的な構文検証を期待できることを意味します。IPアドレスや日付などの形式では、これは完全な検証になると予想されます。電子メールアドレスなどのより複雑な形式では、サポートは依然として大きく異なる可能性があります。どの程度の実装がこのレベルのサポートを提供してきたのかは不明です。

• 語彙エラーの結果とは、実装が語彙の要件を満たすことができないため、スキーマの処理を拒否することを意味します。

ほとんどのドラフト-07以前の実装がすべての形式の厳密で完全な検証を提供していなかったことを考えると、実際にはどの実装もオプション3をサポートするとは考えにくいようです。

さらに、2つの新しい形式が追加され、仕様の参照が更新されました。

コンテンツボキャブラリ

検証仕様、8節

これらのキーワードは、アサーションではなく、純粋にアノテーションとして指定されるようになりました。検証プロセス以外の自動処理をオプションで提供する方法に関するガイダンスが提供されています。

メタデータボキャブラリ

検証仕様、9節

ハイパー スキーマボキャブラリ

ハイパースキーマ仕様、5節と6節