GitHubでJSON Schemaが明白な選択肢となった理由

課題

GitHubは、ソフトウェア開発者や関連分野の専門家にとって、効率的なコード管理、シームレスなコラボレーション、自動化、プロジェクト管理などを可能にする、遍在的で非常に貴重なツールです。1億人以上のユーザーがプラットフォームに依存しており、その多くはオープンソースソフトウェアの構築と共有のために毎日利用しています。

GitHubには驚くほどの機能が詰め込まれており、開発ライフサイクル全体を支援しています。また、この増え続ける機能リストをサポートしているのは、GitHub内で開発された間違いなく強力で複雑な基盤プラットフォームと、新旧の機能を網羅した広範なドキュメントです。

GitHubのドキュメントはdocs.github.comにあり、それ自体がプラットフォーム内の膨大なページの機能を網羅した大規模な事業です。歴史的に、このドキュメントは静的に生成された2つのサイト（help.github.comとdeveloper.github.com）に分割されていましたが、2020年にこれらの静的サイトはdocs.github.comでホストされる新しい動的アプリケーションに統合されました。GitHubのドキュメントの再生の全容は、GitHubブログのこちらとこちらで詳しく説明されていますが、この変更の重要な成果は、データ駆動型ドキュメントへの移行、特にコンテンツの駆動とアプリケーションプラットフォーム自体内での相互通信の両方のためのJSONの利用への大きな投資でした。

具体的には、一部のページコンテンツはJSONデータファイルから完全に自動的に組み立てられ、一部のJSONはコンテンツライターによって手動で作成されます。プラットフォーム内では、アプリケーションのクエリ可能なインメモリコンテキスト全体をJSONとして取得できます。

「JSONデータをJSONスキーマに対して検証できないと、自動ドキュメントページのデータ欠落やページの利用不可などの本番環境でのバグが発生します」と、GitHubのドキュメントエンジニアリングチームで働くソフトウェアエンジニアのRachael Sewell氏とRobert Sese氏は説明しています。

JSONデータに適切なスキーマがないと、コード変更によって新しいバグが導入されたかどうかを確認したり、外部ソースから取得したデータが自動ドキュメントページに必要な形式であることを確認したりする方法がありませんでした。

解決策

チームは、アプリケーションの一部として消費または生成されるすべてのJSONデータファイル、コンテキストデータ、APIリクエスト本文を検証するために、JSONスキーマを導入し始めました。データモデルに変更が加えられるたびに、スキーマはそれに応じて更新され、どのような状況でも、スキーマはアプリケーションが各変更で正しく機能することを検証するために使用されます。

これは主に3つの方法で行われます

• アプリケーションが本番環境で実行されている間、各API呼び出しは、イベントをデータウェアハウスに渡す前に、対応するJSONスキーマを介してリクエスト本文を検証します
• 自動化パイプラインで外部データを取得する場合、データがソース形式からJSONに変換されるたびに、生成されたデータはJSONスキーマに対して検証され、正しく変換されたことを確認します。検証に成功すると、生成されたデータはgitリポジトリにチェックインされ、本番環境で使用されます。そうでない場合、調査のために障害が発生します。

• アプリケーションに変更が加えられるたびに継続的インテグレーションを実行する場合、さまざまな追加スキーマによって以下が保証されます

  • YAML frontmatterプロパティが、アプリケーション内でページを生成するために使用されるMarkdownファイルに正しく含まれていること
  • ページコンテンツを含み、コンテンツライターによって手動で作成されたYAMLまたはJSONデータファイルが正しく形成されていること
  • アプリケーションのサイトツリーとともにサイトコンテンツ全体を含む実行時に作成されたコンテキストオブジェクト自体が正しく形成されていること

「JSONスキーマ検証を可能にするためにJSONスキーマを選択することは、私たちのチームが行った自然で明白な選択でした。これは、約3年前に静的サイトから動的アプリケーションに移行して以来、アプリケーションの基本的な部分となっています。」 - Rachael Sewell氏とRobert Sese氏、GitHubのドキュメントエンジニア

効果

JSONスキーマをプラットフォームに導入することで、生産性、発見可能性、信頼性に大きな影響がありました。

「JSONスキーマを使用することで、データの形状とプロパティタイプをはるかに簡単に確認できます。ディスク上のファイルを開いて、データ構造がどのように見えるかをすばやく理解できます。これにより、スキーマによって支援されるデータに依存する機能を拡張する際に、チーム全体の時間を節約できます。」 - Rachael Sewell氏とRobert Sese氏、GitHubのドキュメントエンジニア

GitHubチームは迅速に動いており、ドキュメントチームは1日に20回以上本番環境にリリースし、変更が意図したとおりに機能することを保証するために、すべてのコミットをチェックする継続的インテグレーションに大きく依存しています。継続的インテグレーションの失敗は、変更が本番環境に送られる前にチームに警告を発します。JSONスキーマ検証は、アプリケーションに必要なJSONデータのさまざまな部分が適切に形成されていることを保証する上で不可欠な要素です。

GitHub - 企業として

GitHubは世界最大の開発者プラットフォームであり、世界中の開発者と組織が安全なソフトウェアを構築、拡張、提供するのを支援しています。

カリフォルニア州サンフランシスコに拠点を置いていますが、採用と職場文化はリモートファーストです。

ここで取り上げた主題に特に関連して、GitHub内には、ドキュメントアプリケーションを担当するドキュメントチームが所属する、教育、コミュニティ、オープンソースソフトウェアと呼ばれる内部組織があります。このドキュメントチームは、コンテンツライター、コンテンツデザイナー、ドキュメントプロダクトマネージャー、ドキュメントデザイナー、ドキュメントエンジニアで構成されています。

素晴らしいdocs.github.comを管理しているGitHubのドキュメントエンジニアリングチームのソフトウェアエンジニアであるRachael Sewell氏とRobert Sese氏、そしてGitHubのチーム全体に、彼らの経験を共有し、私たちがさらにそれを皆さんと共有することを許可してくれたことに感謝します。