カスタムアノテーションは継続されます

前回、未知のキーワードのサポートを削除する必要があった経緯について書きました。その投稿の最後に、非機能的なカスタムキーワード、つまり単純なアノテーションをサポートできる方法をまだ探していると書きました。

今回の投稿では、解決策とその経緯、そして私たちが考え出し、提案された他のいくつかの解決策の簡単な概要について説明したいと思います。しっかりと準備してください。穏やかな乗り心地になるでしょう！

解決策は何ですか？

結論を先に言うと、今後、JSON Schemaは、x-で始まるキーワードをアノテーションとして扱います。

この解決策が選ばれた理由はいくつかあります。

1. アドホックなキーワードは、必然的にそれに関連する機能を持つことはできません。つまり、それらは常にアノテーションにすぎません。その値は、スキーマによる処理なしに、ユーザーまたはアプリケーションに返されるだけです。
2. アドホックなアノテーションが規約に従うことで、非常に簡単に識別できるようになります。
3. プレフィックスは、従うべき良い規約です。
4. このプレフィックスをアドホックなアノテーション用に予約するということは、現在または将来に、ボキャブラリーで定義されたキーワードとの衝突がないことを意味します（互換性の約束を維持します）。
5. 開発者は、HTTPヘッダーなど、カスタムデータを示すために他の分野ですでに一般的に使用されているx-プレフィックスを一般的に認識しています。

x-を使用することに一つだけ躊躇したのは、その起源が実験的な動作を示していたことです。しかし、実際には、このプレフィックスはカスタムデータにはかなり自由に使われているようです。カスタムデータを私たちの表現された目的にしているため、適切であるように思えます。

なぜプレフィックスで、他の解決策ではないのですか？

前回のブログ記事を公開し、できる限りインターネット全体に広めたところ、カスタムキーワードが非常に広く使用されており、それらをサポートしないとユーザーに望ましくない大きな損害を与えるというフィードバックを受けました。アノテーション付きのカスタムキーワードをまだサポートする予定でしたが、それがどのようなものになるかはわかりませんでした。そこで、チームがすでに持っていたいくつかの大まかなアイデアについて議論を開始しました。

その議論には多くのこと、そして非常に多くのアイデアが含まれていますが、ここではいくつかのハイライトについて説明します。詳細に関心がある場合は、議論を自由にお読みください。

代替案＃1 - 新しいキーワードでプレフィックスを定義する

このオプションは、スキーマに使用されるプレフィックスを含む新しいコアキーワード（$で始まるもの）を定義することで、実際に選択したものを構築します。これは、スキーマ作成者が目的のプレフィックスを使用できるという魅力的な概念です。

ただし、スキーマがメタスキーマによって検証されるためには、メタスキーマがこの新しいキーワードを読み取ってプレフィックスを取得し、そのプレフィックスで始まるキーワードを無視できるようにする必要があることが指摘されました。これには、JSON Schemaに現在ない多くの新しいメカニズムが必要となるため、現時点ではあまり実用的ではありません。

また、このキーワードのスコープがどのようになるかについても理解できませんでした。キーワードが使用されたスキーマリソース（$idで示される）のみでしょうか？ドキュメント全体でしょうか？プレフィックスを定義していない別のスキーマリソースまたはドキュメントに$refした場合はどうでしょうか？意図を推測することと、あまりにも多くの繰り返しを要求することの間には、どこかにバランスがあります。

代替案＃2 - 無視するカスタムキーワードを新しいキーワードにリストする

このオプションは、無視するキーワードの名前の配列を保持する$ignoredなどの新しいコアキーワードを定義します。これにより、スキーマ作成者は使用したいキーワードを明示的に定義できます。

代替案＃1と同様に、これには、JSON Schemaに現在、必要となるメタスキーマ検証の種類を実行するメカニズムがないという問題と、同じスコープの問題があります。また、スキーマ作成者が、後で仕様またはいくつかのボキャブラリーに追加されるキーワードを無視する可能性があり、その結果、無視すべきではないため、驚くほど間違った検証につながり、互換性の要件に違反することになります。

代替案＃3 - キーワードを定義するインラインボキャブラリー

このオプションでは、メタスキーマの$vocabularyキーワード内で、ボキャブラリーを定義および記述できるようにします。これは代替案＃2に似ていますが、アドホックなキーワードはボキャブラリーによって定義されるため、「未知のキーワードは不可」を強制する通常のJSON Schemaプロセスはそれらを拾い上げません。つまり、既知になります。

私たちはこれを断念しました。なぜなら、これには、いずれにしても開発中の概念であるボキャブラリーのさらなる開発が必要になるからです。この解決策は、ボキャブラリーの概念をこの問題の解決に向けて歪めることにもなりますが、これはボキャブラリーの概念にとって正しい方向ではない可能性があります。

代替案＃4 - すべてのカスタムアノテーションを含む新しいキーワード

このオプションでは、スキーマ作成者が使用したいカスタムキーワードをすべて格納する$extraなどの新しいコアキーワードを作成します。

望ましくないことに、これにより、アノテーションとアノテーションしようとしているデータの間に分離層が作成されます。しかし、さらに重要なことに、キーワードは（現在定義されているように）単一のアノテーションしか作成できないため、$extraのようなキーワードは、個々のキーワードのようにより的を絞るのではなく、すべてのアノテーションを単一の大きなオブジェクトにまとめます。

代替案＃5 - オプションの背後で未知のキーワードをサポートする

最後に、このオプションでは、実装が未知のキーワードを許可する構成オプションを提供し、「許可しない」をデフォルトにする必要があります。未知のキーワードを許可すると互換性の約束が破られますが、ユーザーがこのオプションを明示的に設定するということは、そのリスクを事実上認めていることになります。

これは後退のように感じました。このプロジェクトで私たちが望むサポートの精神に合致しないように感じたのです。

なぜプレフィックスとしてx-を選んだのですか？

前回の投稿では、議論へのリンクを貼り、誰もがお気に入りのアイデアをサポートしたり、新しいアイデアを提案したりすることを勧めました。過去よりも多くのインタラクションが見られ、それは素晴らしいことでした！

さらに、私たちはソーシャルメディアで議論について投稿し、他の人がブログ投稿や議論（または両方）にリンクして、そのプラットフォームで議論しているいくつかの投稿（たとえばreddit上）も見つけました。

プレフィックスオプションが最も好まれているように見えると判断した後、私たちのコミュニティマネージャーであるベンジャミン・グラナドスは、そのプレフィックスがどうなるかについてのオプションをリストした調査を作成しました。これには、これまでの議論で提案されたもの、x-といくつかの入力しやすい記号、および「自分で作成」オプションが含まれていました。

53人の回答がありましたが、多くはないように見えるかもしれませんが、これまでよりも多いです。結果は、x-（17票）が優先されるプレフィックスであることが明確に示されました。2位タイは、アットマーク@とアスタリスク*でそれぞれ12票でした。

長すぎるので、とにかく読んでください

今後は、カスタムアノテーションキーワードのプレフィックスにx-を使用してください。

このソリューションの良い点は、JSON Schemaの次のバージョンを待つ必要がないことです。今日からスキーマの更新を開始できます。x-キーワードは、現在公開されているすべてのバージョンのJSON Schemaと互換性があり、アノテーションとして収集されるだけです。そして、次のバージョンがリリースされたときには、すでに移行が完了しています！

カバー写真：Mick Haupt（Unsplash）