2022年5月16日（月） ·7読了時間：数分

Node.jsでJSON Schemaを使い始める

ブログに戻る
Simon Plenderleith
@simonplend

Originally published at simonplend.com。

Node.js アプリケーションのリクエスト検証を構築する最初のステップは、柔軟な検証ルールを作成する方法を見つけることです。使用する検証ライブラリを選択しようとすると、予想以上に難しいことがよくあります。それぞれが異なり、どれが他のものよりも優れているのか明確ではありません。

おそらく、以前に独自の検証を構築しようとしたことがあるかもしれませんが、それは面倒で保守が困難になり始めます。信頼できる検証を導入して、アプリケーションの刺激的な新機能の構築に移行したいと考えています。なぜ検証の追加がそれほど頭痛の種なのでしょうか?!

この記事では、JSON Schema 仕様がどのように柔軟な検証ルールの作成に役立つかを学びます。データの期待される形式を記述するスキーマを作成し、Ajv バリデーターライブラリを使用してデータを検証する JavaScript を記述します。

さあ、始めましょう!

強力な検証コンビ

JSON Schema 仕様は、JSON データの構造を記述するための JSON ベースの形式を定義します。type、required、properties などの検証キーワードが含まれています。これらのキーワードを使用すると、データの期待される形式の定義を作成できます。これは「スキーマ」です。次のように単純なものにすることができます

スキーマ
{ "type": "string" }

スキーマに対してデータを検証するには、JSON Schema 仕様を実装するバリデーターライブラリを使用する必要があります。Ajv (Another JSON Schema Validator) ライブラリは、クライアント側とサーバー側の JavaScript 向けの最も一般的な JSON Schema バリデーターであり、npm から毎週 5,000 万回以上ダウンロードされています。

実際に体験して、JSON Schema と Ajv を使用したデータの検証がどのようなものかを見てみましょう。

JSON Schema の詳細な紹介については、ブログ投稿JSON Schema in 5 minutesをご覧ください。

スキーマの作成とデータの検証

まず、npm install ajv コマンドを実行して、Ajv ライブラリをインストールする必要があります。

次に、JSON スキーマの定義に langsung masuk できます。期待される構造と型を記述します

1const iceCreamSchema = {
2  type: "object",
3  properties: {
4    flavour: { type: "string" },
5    price: { type: "number" },
6    stock: { type: "number" },
7  },
8  required: ["flavour", "price", "stock"],
9};

次に、検証するデータを定義します

1const iceCreamData = {
2  flavour: "Pistachio",
3  price: 1.99,
4  stock: null,
5};

次に、Ajv ライブラリをインポートして、新しい Ajv インスタンスを作成します

1import Ajv from "ajv";
2
3const ajv = new Ajv();

そしてそれを使用して、スキーマに対してデータを検証します

1const isDataValid = ajv.validate(iceCreamSchema, iceCreamData);

最後に、検証結果を処理するコードを追加します

1if (isDataValid) {
2  console.log("The ice cream data is valid! 🍨");
3} else {
4  console.error("The ice cream data is invalid:", ajv.errors);
5}

このコードをまとめて実行すると、次の出力が得られます

1The ice cream data is invalid: [
2  {
3    instancePath: '/stock',
4    schemaPath: '#/properties/stock/type',
5    keyword: 'type',
6    params: { type: 'number' },
7    message: 'must be number'
8  }
9]

かなりスムーズですよね？

さて、期待される構造と型を記述するスキーマを作成し、それに対してデータを検証し、検証エラーを処理しました。ここまでは順調です!

編集者からのメモ：AJV の最新のメジャーリリースでは、デフォルトで有効になっている「厳格モード」が導入されました。これは、有効な JSON スキーマが使用されている場合に例外をスローすることがあります。厳格モード関連のエラーで問題が発生した場合は、ドキュメントで無効にする方法、または特定のルールについて詳細を確認してください。これはリンター機能としてより適切であると感じるかもしれませんが、スキーマの作成における偶発的なエラーを防ぐのに役立ちます。 - Ben Hutton

最後のステップとして、JSON スキーマの作成方法を改善する方法を見ていきます。

スキーマ生成

JSON スキーマは検証ルールを定義するための表現力豊かな方法ですが、「手動で」スキーマを作成すると、少し大変になることがあります。fluent-json-schema という便利なライブラリがあり、JSON スキーマの生成に役立ちます。試してみましょう。

JSON スキーマに変換される検証ルールを定義するためのツールを使用すると制御できますが、インスタンスデータから JSON スキーマを生成する他の方法では、部分的に完了した、または場合によっては正しくない JSON スキーマになることがよくあります。他のアプローチは、基本はありますが、完全で使いやすくなるまでにはまだ作業が必要なため、「生成」するのではなく「足場を組む」と呼ばれる方が適切かもしれません。

まず、npm install fluent-json-schema コマンドを実行してライブラリをインストールする必要があります。次に、それをインポートしてスキーマを生成するために使用できます

1import S from "fluent-json-schema";
2
3const iceCreamSchema = S.object()
4  .prop("flavour", S.string().required())
5  .prop("price", S.number().required())
6  .prop("stock", S.number().required())
7  // This method call returns the generated schema as an object.
8  .valueOf();

iceCreamSchema オブジェクトを console.log すると、生成された JSON スキーマを確認できます

スキーマ
{ "$schema": "https://json-schema.dokyumento.jp/draft-07/schema#",...(中略)...}

この生成されたスキーマは、これまで「手作業で」記述してきたiceCreamSchemaとほぼ同じであることに気付くでしょう。手作業で作成したスキーマを、この生成されたスキーマに置き換えることができ、検証は以前と同じように動作します。

アプリケーションをTypeScriptで記述している場合、TypeBoxライブラリは、fluent-json-schemaの優れた代替手段です。

スキーマ生成は個人の好みによります。生のJSONスキーマを「手作業で」記述することを好む人もいれば、スキーマの生成に役立つライブラリを使用することを好む人もいます。両方試してみて、自分に最適な方法を選択してください。

自分で試してみましょう

まとめ

Ajvはスタンドアロンライブラリとして使用することも、Node.jsアプリケーションの構築に使用しているフレームワークと統合することもできます。一部のNode.jsフレームワークでは、Ajvを組み込んでJSONスキーマベースの検証を提供しています。

JSONスキーマとAjvを組み合わせることで、Node.jsアプリケーションに検証を実装するための柔軟なソリューションが得られます。

  • 一度習得すれば、どこでも使用できます。 JSONスキーマ仕様はクロスプラットフォームであり、一般的なプログラミング言語ごとに検証ライブラリが用意されています。ライブラリ、フレームワーク、または言語に縛られることはありません。JSONスキーマの基本を習得すれば、どこでも使用できます。
  • 移植性。 JSONスキーマはクロスプラットフォームであるため、アプリケーションを別のフレームワークまたは言語で書き直す場合でも、スキーマを引き継ぐことができます。
  • 速度。 Ajvは内部でJSONスキーマをJavaScriptコードにコンパイルします。これにより、スキーマに対するデータの繰り返し検証のパフォーマンスが向上します。たとえば、Node.jsアプリケーションの起動時にAjvによってスキーマをコンパイルできます。アプリケーションが受信するHTTPリクエストデータは、プリコンパイルされたスキーマに対して検証できます。
  • 活発で協力的なコミュニティ。 Slackには、喜んで支援してくれる活発なコミュニティがあります（JSONスキーマのWebサイトに参加するためのリンクがあります）。

さらに詳しく

JSONスキーマについてさらに学習したい場合は、これらのリンクが役立つ場合があります。

  • Express APIでのリクエスト検証方法。Express Node.js フレームワークを使用している場合、Ajv ライブラリをアプリケーションに統合するのに役立つガイドを作成しました。
  • Fastify フレームワークの検証ドキュメント。Fastify Node.js フレームワークは Ajv ライブラリを統合しており、JSON Schema を使用した検証を簡単に追加できます。
  • JSON Schema を理解する。JSON Schema の基礎を学ぶことができる無料のオンラインブックです。オフラインで読むための PDF 形式も提供されています。
  • JSON Schema チートシート。JSON Schema の検証キーワードをすぐに参照できるチートシート PDF を作成しました。スキーマを作成するときに役立ちます。

Manik Rathee 氏による Unsplash の写真。