PONOS Advent Calendar 2025の12日目の記事です。

はじめに

json schemaを業務で扱う機会があったのですが、話をふられるまで噂にも聞いたことがない状態でした。
そんな私が「json schema...面白いじゃん」と感じた時期を思い出しながら紹介する記事になっています。
この記事をきっかけにjson schemaを使ってみようかなという人が増えれば幸いです。

そもそもjsonとは？

基本情報

ファイル形式の1つです。
拡張子に「.json」とあればそのファイルはjsonファイルということになります。
Geminiさんによると以下の通りになります。

JSON（ジェイソン：JavaScript Object Notation の略）は、人間にとってもコンピューターにとっても読み書きが容易な、軽量なデータ交換フォーマットです。
これは、Webサーバーとブラウザの間、あるいは異なるシステム間でデータをやり取りする際の「共通言語」として、現在のIT業界で最も広く使われています。

つまりjsonファイルでデータを扱うと軽くて便利ということです。
ちなみに私はマスターデータによく活用します。

基本構造

Visual Studio Codeで新規作成して適当にオブジェクト型のデータを書いてみると「おっ、これはjsonファイルに違いない！」と判断してくれます。(配列型も可)

そんなjsonの基本構造ですがGeminiさんによると以下の通りになります。

JSON（JavaScript Object Notation）は、データを表現するために、たった2つの基本構造と、いくつかの値の型のみを使用します。

オブジェクト（Object）
現実の「モノ」や「概念」を表現するのに使われます。
定義: 波括弧 { } で囲みます。
構造: キー（名前）と値（Value）のペアをコンマで区切って並べます。
特徴: キーは必ずダブルクォーテーションで囲まれた文字列です。
例:
JSON
{
 "product_name": "Laptop",
 "price": 99800
}
配列（Array）
データのリスト（一覧）を表現するのに使われます。
定義: 角括弧 [ ] で囲みます。
構造: 複数の値をコンマで区切って並べます。
特徴: 要素の値は、型が異なっていても構いません。
例:
JSON
[
"Tokyo",
"Osaka",
"Nagoya"
]
値として使える型
オブジェクトや配列の中に含まれる「値」として使用できるのは、以下の6種類です。
・文字列 ("...")
・数値 (整数、浮動小数点数)
・真偽値 (true / false)
・null
・オブジェクト ({})
・配列 ([])

使える型は限られますがオブジェクトと配列を駆使してデータを形作ったもの、それがjsonの基本構造となります。

json schemaとは？

ではjson schemaとは何か？
まずはGeminiさんによるお手本を聞いてみます。

JSON Schemaを一言で言えば、「JSONデータの構造、形式、および制約を定義するための、JSON形式のルールブック」です。
これは、私たちが「こういう形のデータだけを受け付けますよ」「ここにあるデータは必須ですよ」とあらかじめ宣言するための設計図であり、データに関する契約書のようなものです。
このSchemaを定義しておけば、以下のことが可能になります。
バリデーション（検証）: データを受け取る前に、このSchemaと照らし合わせて自動的にデータの妥当性をチェックできます。期待通りの形式でなければ、処理を始める前に弾くことができます。
ドキュメント生成: Schemaを見れば、データ構造が一目瞭然なので、データ仕様書として利用できます。
入力補助: 開発ツールの設定などにSchemaを使えば、入力時のオートコンプリートやエラーチェックが可能になります。
JSON Schemaを学ぶことは、データの信頼性と開発効率を劇的に向上させるための第一歩なのです！

つまり「このjsonデータはこういうデータがあってこのような値が入っている」を定義する。
それがjson schemaの役割です。
使い道としては、データがスキーマに書かれている定義から外れていないかを厳密にチェックし、「ここがおかしいよ！」と警告を出して教えてくれることです。
具体的に、JSON Schemaがどのようなデータのエラーを未然に防いでくれるのか、今回は4つの例を見ていきましょう。(長くなるので最初は流し読み推奨)

1.型の不一致

"type": "型名"でデータに入る値の型を指定することができます。
例えば"type": "object"でオブジェクト、"type": "integer"で数値を指定します。

「データ「age」には数値(integer型)が入る。」というjson schema

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "properties": {
        "age": {
            "title": "年齢",
            "type": "integer"
        }
    }
}

ageに数値ではなく文字列を入れると...

2.範囲外の値

"minimum"や"maximum"は値の範囲を指定することができます。
"minimum"は最低値、"maximum"は最大値を表します。

「データ「HP」には数値(integer型)が入り、最低値は0、最大値は999。」というjson schema

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "properties": {
        "HP": {
            "title": "体力",
            "type": "integer",
            "minimum": 0,
            "maximum": 999
        }
    }
}

HPに0~999以外の数値を入れると...

例えばうっかり桁を１つ多く入力してしまったミスなどがなくなるでしょう。

3.データ最低数・最大数の指定

データ数そのものの数を指定することもできます。(キーワードは型によって様々)
"minItems"では配列の要素数の最低数、"maxItems"では配列の要素数の最大数を表します。
以下の例のように"minItems"と"maxItems"を同じ数字にすると要素数はその数字ピッタリでないといけないと言う意味になります。

「配列「List」には最低50個、最大50個の要素がある。」というjson schema

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "properties": {
        "List": {
            "type": "array",
            "minItems": 50,
            "maxItems": 50
        }
    }
}

たくさんデータがあって目視では見逃しやすいミスも防げます

4.必須項目の指定

キーワード"required"は要素の必須を表します。
"required"リストに必須にしたいデータを入れておくと存在しない時に警告を出してくれます。

「データ「name」には文字列が入り、データ「age」には数値が入る。またデータ「name」は必ず存在する。」というjson schema

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "properties": {
        "List": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "name": {
                        "title": "名前",
                        "type": "string"
                    },
                    "age": {
                        "title": "年齢",
                        "type": "integer"
                    }
                },
                "required": [
                    "name"
                ]
            }
        }
    }
}

このようにデータがないと警告を出してくれます。
逆にそれ以外の要素はあってもなくてもどちらでも問題ありません。

誤字の発見などに繋がります。

間違いを指摘してくれると言うのはこのようなことを指します。
逆に数値が1違うとかデータと値がずれているとかは対応してくれません。(そういうjson schemaを組めれば対応可能かもしれませんが...)

ゲームで例えると「ステータスにHPがないのはおかしい！」「HPがマイナスなのはおかしい！」みたいなのは警告を出してくれますが「本来はHP:30のところを40と書いてしまった」「攻撃力と防御力を逆に書いてしまった」みたいなのはスルーする塩梅です。うまく付き合っていきましょう。

今回は割愛しますが他にも勝手に値を補完してくれるdefaultや型を自作して使い回すdefsなどデータのルールを形作るのに便利な機能がたくさんあります。使いこなすことができればデータに色々なルールを課すことができるでしょう。

json schemaを使ってデータをチェックしてみる

本来はAPI開発やゲームエンジンのツールとして利用するらしいのですが、今回はJSON Schemaの強力なチェック機能を手軽に体験してもらうため、Visual Studio Code（VS Code）の組み込み機能を使った簡単な検証方法を紹介します。

この方法なら、面倒な外部ツールのインストールは不要です！

環境

Visual Studio Code
MacOS

1.フォルダを用意する

場所はどこでも良いのでフォルダを1つ用意します。
このフォルダの中にjsonファイルとjson schemaを格納します。

2.jsonファイルを用意する

作成したフォルダにjsonファイルを入れます。
Visual Studio Codeを起動し、ファイル→新しいテキストファイルを選択してさらのテキストファイルを作成、中にjsonデータを書きます。
今後のためにわざとおかしな値(スキーマで警告を起こすような値)を書いておくと最終的にうまく行ったときに一目瞭然です
自身で書いても良いですが面倒な方は以下のテキストをコピー＆ペーストしちゃってください。(大したものではないですが)

今回は一例として履修登録のデータをイメージして作成しました

{
    "name": 0,
    "registeredCourses": [
    "化学",
    "物理"
  ]
}

保存したら保存先と名前を聞かれるので保存先は先ほど作成したフォルダを選択し適当に名前を変更してください。ただし拡張子は.jsonになるように気をつけてください。

3.json schemaファイルを用意する

手順はjsonファイルと同じで保存先も同じフォルダの同じ階層に保存してください
こちらにもコピー＆ペースト用のテキストを置いておきます。
"description"キーワードを使うと説明を載せられるのでどんどん使いましょう。

今回は一例として履修登録のデータをイメージして作成しました

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "学生の履修登録スキーマ",
  "description": "学生が登録した科目と基本情報を検証します。",
  "type": "object",
  "properties": {
    "name": {
      "title": "氏名",
      "type": "string",
      "description": "氏名は文字列である必要があります。"
    },
    "studentId": { 
      "title": "学籍番号",
      "type": "integer",
      "minimum": 10000,
      "description": "学籍番号は5桁以上の整数である必要があります。"
    },
    "registeredCourses": { 
      "title": "登録済み科目リスト",
      "type": "array",
      "description": "学生が登録した科目名（文字列）のリスト",
      "minItems": 3,
      "maxItems": 5, 
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "studentId",
    "registeredCourses"
  ]
}

4.「.vscode」フォルダを作成

作成したフォルダ直下に設定用の特殊な「.vscode」フォルダを作成します。
Finderからでは.から始まるフォルダ名は指定できないのでVisual Studio Codeから作成します。
ファイル→開く...を選択するとフォルダの選択画面が出てくるので作成したフォルダを選択します。

正しく選択できればこのような画面なのではないでしょうか

一番上には🔎「あなたがフォルダにつけた名前」とかかれ、jsonデータとjson schemaのファイルが1つずつ存在しています。
この状態で左上の2枚の紙のボタンを押すと以下のような画面が出てきます。

この画面の上のようなマークを押すとフォルダ名を入力する欄が現れるためそこに.vscodeと入力します。
以下のようになっていれば成功です。

5.「.vscode」フォルダに設定ファイルを置く

次に、Visual Studio Codeに「どのJSONファイルに、どのスキーマファイルを適用するか」を教える設定ファイルを用意します。
「.vscode」フォルダ直下に「settings.json」という名前のファイルを作成します。(ファイル名は間違えないように(1敗))
この中には以下のように書いてください

{
    "json.schemas": [
        {
            "fileMatch": [
                "data.json"
            ],
            "url": "./schema.json"
        }
    ]
}

ここに入る"data.json"とはチェックしたいjsonデータのファイル名を書き、"./schema.json"の"schema.json"には用意したjson schemaファイル名を書いてください。

もしうまくいかないときは、
・"url": "schema.json" (スラッシュなしのファイル名のみ)
・"url": "/schema.json" (ルートスラッシュ付き)
・絶対パス
など、様々な記述方法を試してみてください。
これはVS Codeの設定が環境によって異なる場合があるためです。

これで準備はバッチリです

6.再起動

最後に一旦Visual Studio Codeを再起動させます。
改めてVisual Studio Codeでファイルを指定しjsonデータを開くと同期されています。もしこの時点でデータに問題があれば即座に警告が出ていると思います。
こちらで用意した一例では「出席番号がない」「氏名が文字列じゃない」「登録済み科目リストに含まれる要素が少ない」で3つ警告が出ます。

あとはスキーマとjsonデータを自由にこねくり回して遊んでみてください。特に思いつかないのであれば先ほどの紹介の部分に戻って片っ端から試してみることから始めるのも良いかもしれません。あれはできるかな？こんなのはできるかな？と試していくうちに理解が深まると思います。

最後に

いかがだったでしょうか。
json schemaは大きいデータを扱う時やデータに保険をかけたい時、データをルールでガッチガチに縛りたい時などにおすすめです。
いきなり仕事の本番や大きな案件で使うのはハードルが高いと思うのでまずは今回紹介した方法で遊んでみてください。スキーマがどんな事に使えるのか理解することでアイディアが湧くかもしれません。わざと警告を吐くような値を入れてみたり案外楽しいですよ。

読んでいただきありがとうございました。
それでは次回は@FW14Bさんです。