生産性向上 API設計 APIナレッジベース

JSON Schemaとは？便利な生成方法をご紹介！

API開発中によくJSON Schemaを利用する必要があります。本文では、JSON Schemaとは何かを解説した上、その便利な生成方法を皆さんに紹介します。

shimizu chioka

Updated on 2024年4月18日 6 min read

API開発中によくJSON Schemaを利用する必要があります。本文では、JSON Schemaとは何かを解説した上、その便利な生成方法を皆さんに紹介します。

💡

Apidogでは、既存のJSON Schemaをインポートして直感的に編集したり、UIを使って新しいJSON Schemaを設計して生成したりできます。生成したJSON Schemaに基づいてモックデータをプレビューでき、APIレスポンスの構造定義にも適用できるので、API開発の効率化と品質向上に大きく貢献します。

また、Apidogは完全無料で利用可能なツールになりますが、次のボタンからこのツールを無料で取得することが可能です。

button

JSON Schemaとは

JSON Schemaは、JSONデータの構造とバリデーションルールを定義するための言語および仕様です。JSONはデータのシリアライズ形式として広く使用されており、JSON Schemaはそのデータの構造を定義し、有効性を検証するためのツールです。

JSON Schemaは、JSONデータのキー、値、オブジェクト、配列、データ型、制約などの要素を指定するためのスキーマ言語です。スキーマは、データが特定の形式に従っているかどうかを検証するためのルールや条件を定義します。

例えば、JSON Schemaを使用して、次のようなバリデーションルールを定義することができます:

プロパティの存在と必要性の検証
プロパティのデータ型の検証（文字列、数値、真偽値など）
プロパティの範囲の検証（最小値、最大値、最小長、最大長など）
制約の検証（正規表現、列挙値など）
オブジェクトのネストや配列の要素の構造の検証

JSON Schemaは、データのバリデーションやドキュメント化、データの品質管理などのさまざまな目的で使用されます。また、JSON SchemaはJSONデータの自己文書化にも役立ちます。さまざまなプログラミング言語やフレームワークでJSON Schemaをサポートしており、JSONデータのバリデーションやスキーマ駆動型の開発に利用することができます。

JSONスキーマの用途

上記のように、JSONスキーマ(JSON Schema)は、JSONデータの構造を定義するための規格として、主な用途は以下の通りです。

データ検証
JSONスキーマを使うと、JSONデータが期待される形式に従っているかどうかを検証できます。プロパティの型、必須項目、範囲など、様々な制約を設定できます。これにより、不正なデータを事前に検知し、エラーを防ぐことができます。
ドキュメント生成
JSONスキーマには、プロパティの説明やサンプル値を記述できます。これらの情報を利用して、APIドキュメントなどを自動生成することができます。
データ変換
JSONスキーマを使って、JSONデータを別の形式に変換したり、デフォルト値を設定したりすることができます。
開発支援
JSONスキーマを利用することで、IDEやエディタでインテリセンスやコード補完の機能を提供できます。開発者は構造を意識せずにJSONを編集できるようになります。
データ生成
テストデータの自動生成などに利用できます。JSONスキーマに基づいて、ランダムなJSONデータを生成することができます。
スキーマ検証
JSONスキーマ自体も、メタスキーマに対して検証することができます。これにより、JSONスキーマの正当性をチェックできます。

JSONスキーマは、JSON形式のデータを扱う際の品質保証や開発効率化に役立ちます。特にWeb APIなどでJSONを使う場合に有用です。

JSON Schemaの例

JSON Schemaに対する理解をさらに深めるために、以下は、簡単なJSON Schemaの例を紹介します。

JSONデータ

{
  "name": "John Doe",
  "age": 30,
  "email": "john.doe@example.com",
  "address": {
    "street": "123 Main St",
    "city": "New York",
    "state": "NY",
    "zip": "10001"
  },
  "phoneNumbers": ["123-456-7890", "987-654-3210"]
}

JSON Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "age": {
      "type": "integer",
      "minimum": 18
    },
    "email": {
      "type": "string",
      "format": "email"
    },
    "address": {
      "type": "object",
      "properties": {
        "street": {
          "type": "string"
        },
        "city": {
          "type": "string"
        },
        "state": {
          "type": "string",
          "maxLength": 2
        },
        "zip": {
          "type": "string",
          "pattern": "\\d{5}"
        }
      },
      "required": ["street", "city", "state", "zip"]
    },
    "phoneNumbers": {
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "\\d{3}-\\d{3}-\\d{4}"
      }
    }
  },
  "required": ["name", "age", "email", "address", "phoneNumbers"]
}

この例では、JSONデータの構造とバリデーションルールが定義されています。例えば、"name"プロパティは文字列型である必要があり、"age"プロパティは18以上の整数である必要があります。"email"プロパティはメールアドレスの形式に準拠している必要があります。

また、"address"オブジェクトは、"street"、"city"、"state"、"zip"のプロパティを必須とし、それぞれのプロパティにも検証ルールが定義されています。"zip"プロパティは、5桁の数字でなければなりません。"phoneNumbers"は配列であり、各要素は電話番号の形式（例: "123-456-7890"）に準拠している必要があります。

JSONデータがこのJSON Schemaに合致している場合は、バリデーションが成功し、データは有効であるとみなされます。

API開発中にJSON Schemaの利用

JSON Schemaは、多くのプログラミング言語やフレームワークでサポートされており、API開発においてデータのバリデーションやドキュメント化のために広く利用されています。

API開発において、JSON Schemaは以下のような利点を提供します。

リクエストのバリデーション

JSON Schemaを使用して、受け入れるリクエストの形式を定義し、受信したデータがスキーマに準拠しているかを検証できます。これにより、不正なリクエストの受け入れを防ぎ、予期しないデータの処理を防ぐことができます。

レスポンスのドキュメント化

JSON Schemaを使用して、APIのレスポンスの構造を定義することで、開発者やAPIの利用者に対してAPIの仕様を明確に伝えることができます。これにより、APIの利用方法や期待されるレスポンスの形式を理解しやすくなります。

自己文書化

JSON SchemaをAPIの一部として提供することで、API自体が自己文書化される効果があります。開発者はAPIのエンドポイントやデータ構造を簡単に理解し、正しいリクエストとレスポンスを作成できるようになります。

クライアント側の生成

JSON Schemaを使用して、クライアント側のコードやドキュメントを自動生成することができます。これにより、APIの利用者はAPIの使用方法やデータの形式に関する手間を減らすことができます。

データの品質管理

JSON Schemaを使用して、受信したデータがAPIの要件を満たしているかどうかを検証することで、データの品質管理を強化できます。データの整合性やバリデーションエラーのチェックにより、信頼性の高いデータを保証することができます。

完璧互換のApidogでJSON Schemaの生成と解析

Apidogは、Jsonスキーマに完璧に互換できるAPIライフサイクル管理ツールです。API開発中に、Jsonスキーマを使用したい場合、Apidogは、Json Schemaのデータを解析して、それを繰り返し利用可能なデータ構造に変換することができます。また、Apidogで直感的操作で各項目を設定して、Jsonスキーマを1クリックで生成することもできますし、JSON Schemaのデータ構造に従って、データのモッキングも実現することもできます。

API開発中にJSON Schemaに対して何かのニーズがあっても、Apidogはそれを満たすことができると思います。JSON Schemaのほか、Apidogはデータベーススキーマ、XMLなどのスキーマ言語にも対応できます。

button

JSON Schemaの認識と解析

既存のJSON Schemaをお持ちの場合、Apidogはそれを簡単に認識して直感的な設定項目に解析することができます。

ステップ⒈Apidogで「新しいSchema」をクリックして、スキーマを新規に作成します。スキーマの新規作成画面で「JSON/XMLスマート認識」をクリックします。

ステップ⒉ここで「JSON Schema」を選択して、JSON Schemaをここにコピーして、「OK」ボタンをクリックします。

ステップ⒊入力したJSON Schemaが解析され、直感的で変更可能な項目に変換できます。

ステップ⒋ここで「プレビュー」をクリックして、JSON Schemaのデータ構造に従って、データをモッキングして真実なJSONデータを生成することもできます。

Apidogに内蔵されているモックルールもありますし、自分でモックルールをカスタマイズすることもできます。

button

JSON Schemaを1クリックで生成

また、JSON Schemaを自分で設計して生成したい場合Apidogを使用するのも便利です。次のステップを参照して、非常に直感的な操作によって、JSON Schemaを簡単に生成できます。データ構造の設計が終わると、「コード生成」をクリックします。

ステップ⒈Apidogで「新しいSchema」をクリックして、スキーマを新規に作成します。スキーマの新規作成画面で自分の必要に応じて、データ構造を直感的なUIで設定して、各項目を追加すると、「JSON Schema」をクリックします。

ステップ⒉ここで設計したデータ構造に従って生成するJSON Schemaが表示されます。ここで生成したJSON Schemaをコピーすることもできます。

button

API開発中にJSON Schemaを便利に利用

ApidogでJSON Schemaを再利用可能なデータ構造にすることができるので、APIのリクエストのバリデーション、レスポンスの整形、やテストのサンプルデータの作成の時に、1クリックだけでそのJSON Schemaによるデータ構造を参照できます。

ステップ⒈JSON SchemaをApidogでデータ構造として保存すると、左側のメニューの「Schema」から確認できます。

ステップ⒉APIを作成・変更する時に、「Response」の部分で、「追加」ボタンをクリックして、新しいレスポンスを定義します。

ステップ⒊ここで新しいレスポンスを設定します（コンテンツ形式をJSONとする必要あり）。Schema参照をクリックして、先に追加したJSON Schemaを選択します。

ステップ⒋ここでJSON Schemaの全ての項目を追加しました。

ステップ⒌画面を少し下にスクロールして、「例を追加」して、「自動生成」ボタンをクリックして、当該JSON Schemaに従ってAPIのレスポンス例を生成することもできます。

button

まとめ

JSON Schemaは、JSONデータの構造を定義したもので、さまざまな場合で広く利用されています。API開発中に、リクエストのバリデーション、レスポンスの定義、APIドキュメンテーションなどの場合でも、JSON Schemaを活用する必要があります。

ApidogはJSON Schemaに完璧に互換できるので、JSON Schemaの認識と解析を実現することもできますし、JSON Schemaのデータ構造を直感的なUIで設計したり、生成したりすることもできます。また、最も重要なことに、ApidogはJSON Schemaを再利用可能なデータ構造に変換することができるので、APIの開発効率をかなり高めることができます。

JSON Schemaとは？便利な生成方法をご紹介！

shimizu chioka

JSON Schemaとは

JSONスキーマの用途