システム
ライト
ダークご紹介：Bowtie
ブログに戻るこれは、Bowtieに関する断続的なシリーズの最初の記事です。ここでは、JSON Schema組織を代表して公式な立場から発言するものではありません。Bowtieは、JSON Schemaチームが今日何らかの形で「推奨する」ツールではありません。しかし、個人的には公式ツールのようなものになることを願っており、「コミュニティ」に所有されることを意図して開発しました。現時点では、私は著者としてのみ発言しています :)。
JSON Schema
スキーマ最大長が3の文字列を検証します。この動作は、仕様でそうなるはずと規定されているものです。幅広いプログラミング言語にわたる仕様のすべての実装が、仕様を適切に守っているでしょうか？他のより複雑なスキーマ/インスタンスのペアについてはどうでしょうか？これがBowtieが解決しようとしている重要な問題です。JSON Schema実装間、および仕様間の動作の違いを比較し、実装上の問題を修正しやすくし、仕様の不明確な部分を明確にするにはどうすればよいでしょうか？
概要
Bowtieは、私が「メタバリデーター」と呼んでいるもので、これは他のJSON Schema検証実装を実行し、それらから結果を収集できるプログラムを意味します。
この種のことを行うための先行事例はあります。 JSONPath ComparisonプロジェクトはJSONPathに対して非常にうまくこれを行っており、Nicolas Seriotの「Parsing JSON is a Minefield」はJSON自体の素晴らしい例です。BowtieはこれらのアイデアをJSON Schemaに適用しようとしています。
既存のJSON Schema実装リストから、Bowtieはすでに12の実装を9つのプログラミング言語にわたってサポートしており、誰でもこれらの実装を実行し、スキーマとインスタンスについてどのようなことを言うかを確認できます。
コマンドラインプログラムが付属していますが、おそらくよりエキサイティングなのは、このCLIの継続的な自動実行が設定され、Bowtieがサポートされているすべての実装に関するレポートを生成していることです。
このレポートを作成するために、Bowtieは公式のJSON Schemaテストスイートを実行します。これは、JSON Schema仕様への準拠を検証するための既存のテストセットです。多くの実装はすでに継続的インテグレーション内でスイートを使用していますが、JSON Schemaのユーザーと実装者の両方が、単一の場所で、多くの実装にわたってスイートを実行した結果を確認できるのはこれが初めてです。テストスイートはすでに仕様（特に検証部分）を十分にカバーしています。スイートは確かに完璧ではありませんが、したがって、Bowtieの結果は検証仕様を非常によくカバーしています。
なぜ面白いのか
Bowtieが実現する最も注目すべきことは、実装が仕様にどれだけ近いかを比較する簡単な方法です。これにより、実装のユーザーと、実装が難しい可能性のある領域や、一般的に誤って実装されている領域について、コミュニティに透明性がもたらされます。私たちの希望は、これが問題の修正を支援するための改善とエネルギーにつながり、全体としてより強力なコミュニティにつながることです！
テストスイートを超えても、Bowtieはサポートする実装への統一されたインターフェースを提供できます。つまり、各実装が提供する言語固有のAPIを学習する必要なく、各実装からの結果にすばやくアクセスできます。スキーマとインスタンスがあり、多くの実装で実行したい場合、または既によく知っていないか設定していない単一の実装を実行したい場合、Bowtieが役立ちます。
実行方法
テストスイートの実行に関するレポートなど、その出力にのみ関心がある場合は、現在、次のリンクで仕様の各バージョンに対応するものを見つけることができます。
中期的な目標は、これらを1つの統一されたレポートにまとめることです（その時点でリンクは変更される可能性がありますが、うまくいけばリダイレクトを配置します）。
テストスイートレポート以外にも実行したい場合は、任意の入力でBowtieをローカルで実行することもできます。BowtieはPythonで記述され、PyPIで公開されています。Pythonアプリケーションをインストールするための既存の推奨設定がない場合は、OS固有の手順に従ってpipxをインストールし、次に以下を実行します。
1$ pipx install bowtie-json-schemaこれでBowtieが動作するはずです。以下で確認できます。
1$ bowtie --help使用方法については、Bowtieのドキュメントに記載されていますが、より多くのドキュメントが間違いなく必要なので、もしわからないことがあれば、私（Julian）までご連絡ください。ドキュメントを作成するモチベーションになります。
仕組み
この投稿ではBowtieの実装の詳細には立ち入りませんが、大まかに言うと、BowtieはPythonで記述されたコマンドラインプログラムであり、OCIコンテナ（「Dockerコンテナ」は大まかな意味で）のスピンアップとダウンを調整します。実行するコンテナは「テストハーネス」です。これは、あらゆるプログラミング言語で記述されたJSON Schemaの実装を取り込み、Bowtieからの受信リクエストがテスト対象のライブラリを呼び出すことができる小さなブリッジプログラムです。実装のサポートを追加するということは、本質的にこの方法でテストハーネスを実装することを意味します（これは通常簡単です）。ハーネスが存在すれば、実装はBowtieのレポートで強調表示され、Bowtieのユーザーは誰でもBowtieの統一されたCLIを介して実装を実行できるようになります。
協力方法
JSON Schemaのユーザー、実装の作成者、またはコミュニティメンバーであるあなたは、次の2つの分野で協力できます。
実装の改善
最初で最も明白なことは、Bowtieによって発見された問題を（確認後）、実装にフィードバックし、実装が問題を修正するのを支援することです。
お気に入りのJSON Schema実装を見つけ、それが失敗するテストを確認してください。実装のバグトラッカーに、その失敗に関する既存のオープンな問題はありますか？もし以前に知られていない問題であれば、最小限の再現手順を含めたイシューチケットは、実装者にとって歓迎される可能性が高いので、提出することを検討してください。もし既知の問題であれば、Bowtieにプルリクエストを提出して、その下流の問題に関する情報を含めることができます。Bowtieはレポートで（テストが明示的にスキップされていることを示すことで）この情報を利用できます。その方法を示すプルリクエストの例を参考にしてください。
近い将来、あなたの仕様適合性を誇示するために使用できるBowtie生成バッジにご注目ください（これほどクールなものはないでしょう？）。
Bowtieの改善
2つ目は、Bowtie自体の改善に貢献することです。これについては、私が既に多くのアイデアを持っており、より多くの人が使い始めるにつれて、さらに増えるでしょう。
上記の一部を繰り返しますが、私自身が多くの実装のサポートを実装しました。あなたが実装を管理または使用している場合は、私が書いたハーネスを見てください。あなたの実装を誤用している可能性があります（ありがたいことに今のところは起きていません）。
また、こちらのライブストリームでBowtieに関する作業を試していることも言及しておきます。自己宣伝は控えめにして、気軽に立ち寄って挨拶してください。または、私がBowtie関連のさまざまな問題と格闘している過去のストリームを見てみてください。作業方法に関するヒントが得られるかもしれません。
以下に、支援が必要な分野に関する具体的なガイダンスを示します。
これはこの記事の公開時点での情報ですが、私の希望としては、すぐに古くなることを願っています。もし古くなっているようでしたら、お気軽にご連絡ください！
入門に最適な簡単なものを教えてください
Bowtieのイシュートラッカーには、私がキュレーションを試みた良い最初のイシューのリストがあります。これらは、Bowtieのコードベース（Python部分、フロントエンド部分、およびその周辺のインフラストラクチャ）のさまざまな部分をカバーしています。ラベルは、イシューの修正が必ずしも「小さい」ことを示しているわけではありませんが、多くはそうです。しかし、関連する機能や修正が「単純」であるか、スコープが適切に定義されている可能性が高いことを示しています。もし活動が見られない場合は、作業を開始する際にコメントを残してください。
新しい実装またはプログラミング言語について学びたい
これはおそらく最も「楽しい」作業であり、少なくとも私は非常に楽しんでいました。実装のリストからBowtieがまだサポートしていない実装を選択し、ハーネスを作成するためのチュートリアルに従ってください。これにより、Bowtieがハーネスに期待する内容を理解できます。チュートリアルにギャップがある場合は、それらを提起するか、私に連絡してください！これは、あなたが以前に使用したことのない言語で簡単なプログラムを試すのに良い方法であり、既によく知っている実装とは異なる選択をした可能性のあるJSON Schemaの実装を学ぶ方法にもなります。
レポートが醜い、私は手伝うことができるフロントエンド開発者またはUIデザイナーです
これはおそらくあなたが最も貢献できる分野です。私がフロントエンド開発者ではないことは、明らかでしょう。私が（Bootstrapを使って）まとめたものは、Bowtieが出力する結果を表示するために必要な最小限のものでしかありません。もしあなたがテスト結果を効果的にレポートする方法や、実装を比較する方法について、より多くの経験や発想をお持ちでしたら、ぜひご協力ください！Bowtieの「フロントエンドコード」は現在すべて、1か所にあります。それは、Jinja2テンプレートであり、静的なシングルページサイトにフォーマットされます。「一般的に、より美しく、よりレスポンシブに、またはより使いやすくする」ことに加えて、注目すべきいくつかの具体的な問題があります。
- クライアント側のフィルタリングとソートを追加する
- 結合されたエラー+失敗のカウントを表示する、またはより一般的に、「カウントの表」から、実行で何が起こったかをよりグラフィカルに表現した要約に改善する。
- スキーマとインスタンスをより綺麗に表示する、またはより一般的に、テストケース、それらのスキーマ、インスタンス、および（サブ）テストを表現するための適切なウィジェットまたはコンポーネントを設計する。
- 平均的な適合数を表示する、またはより一般的に、実装全体でどのような要約統計を表示すべきか、そしてどのように表示すべきか？
私はJSON Schemaエコシステムで他のツールを開発しています
素晴らしい！私は、Bowtieが他の上流または下流のツールと上手く連携できることを願っています。具体的な例として、Bowtieが下流の実装に統一されたインターフェースを提供することを考えると、「明白な」補完ツールは、すべての実装にわたってファズテストを行い、実装が意見を異にしたり、クラッシュしたり、より一般的には仕様に準拠しない動作を生成するケースを探すことでしょう。これは、スイート内の明示的なテストではまだカバーされていません。この実行はおそらく、そのようなツールをBowtieに接続して、実行させることを意味します。詳細についてはこのイシューを参照してください。ただし、上記以上の詳細な情報はあまり含まれていません。
他のツールも、Bowtieと組み合わせることで優れたインタラクティブなプロパティを持つ可能性があるため、他のアイデアがあれば、お問い合わせいただくか、試してみてください！
テストを投稿したい
これも間違いなく役立ちます。それらが仕様自体のテストである場合は、公式スイートに既に存在するかどうかを確認し、存在しない場合は、そこに提出してください。それらが、例えば、実装に「クラッシュ」を引き起こすような病的なケースをカバーするため、公式スイートが現在カバーしていないテストである場合、これらは（どこかに、未定の場所ですが）追加する「公平なゲーム」になりました。Bowtieは、実装を「優しく」実行して、これらの種類のエラーをキャッチできるからです。Bowtieは、特に実装が参照できるスキーマの「レジストリ」をハーネスに組み込むプロトコルのため、より広範囲の$ref関連のテストも可能です。このイシューが関連するものですが、ここに追加できるテストの種類についてのアイデアも歓迎します。
バグを見つけた、またはBowtie自体に関するアイデアがある
それが実装に関するものである場合は、実装のイシュートラッカーに提出する必要があります。問題がBowtie自体によって引き起こされている可能性は低いですがゼロではないため、丁寧にお願いします。また、そうでなくても、メンテナーに親切にしてください。多くの人（私も含めて！）は、Bowtieがフラグを立てている問題を既に認識しており、本当に修正したいと思っていても、そうすることを困難にする要因があるかもしれません。可能であれば、実装を支援してください！
Bowtie自体に関するものである場合、またはBowtieに関連する新しいアイデアである場合は、必ずイシューを提出するか、ディスカッションを開始するか、JSON Schema Slackでスレッドを開始してください。
ランダムでクールなことをしたい
このビンには、既にあるものも含めて、いくつかの奇抜なアイデアがあります。テストするだけでなく、実装を均一にベンチマークするためにBowtieを利用できるかどうかを解明したいと考えています。言語固有のREPLに飛び込むことができるようにすることも、ちょっと変わったアイデアですが、試してみるのも楽しいかもしれません。他にも多くのアイデアがあるでしょう！
Bowtieの設定は難しかったが、なんとか解決した / CI、「インフラストラクチャ」またはトリアージを手伝いたい
これらはすべて、あなたが貢献できる過小評価されている分野なので、この分野に興味がある場合は、ぜひご連絡ください。Pythonを使用しない人向けにBowtieのインストールを容易にすることのようなことでさえ、素晴らしい助けになります。（現在、ビルドはshivを生成しますが、クロスプラットフォームのものではありません。）
結論
Bowtieについて少し聞いていただきありがとうございます。また、コミュニティのためにこのような作業を行うために私をフルタイムで雇用してくれているPostmanにも特別な感謝の意を表します。Postmanがなければ、この作業は実現しなかったでしょう！今後も多くのことがあることを願っています。フィードバックをぜひ共有してください。とても歓迎します。また、参加をご希望の場合は、大変感謝いたします！
カバー写真はStable Diffusionで生成されました。