お仕事でPowerAutomateワークフローの構築・運用をする中でしばしばお世話になっているJSON Schema。直近その仕様を確認する機会があったので、その結果をご紹介。

PowerAutomateでは「JSONの解析」アクションでこのJSON Schemaを使用。ふつうは「サンプルから生成」機能で、既存のJSONを元に自動導出するはず。
ただサンプルはあくまでサンプル。実際にフローを実行してみると、サンプルベースのスキーマでは不十分で、自動導出されたスキーマに手を加えないとならないことも。
そうした時の参考になるかと。

JSON Schemaとは？

IETFという標準化団体のもとで標準化されているJSONデータの構造を定義するための言語。
構造定義によりJSONを用いたアプリケーション間のコミュニケーションの生産性・品質を向上させる。
AjaxやRESTfulAPIの普及とともにその必要性が生じ、近年ではシングルページアプリケーションのデファクト化やマイクロサービス化とともに重要度が上がっている状況。
Swagger（OpenAPI）でもJSON Schemaのサブセットが利用。
定義そのものがJSON形式で記述。
仕様には複数バージョンあり、スキーマ生成・解釈をする実装ごとにサポート状況に差がある点は要注意。

参考ページ

スキーマ例

次のようなJSONがあるとき、

{
  "productId": 1,
  "productName": "A green door",
  "price": 12.50,
  "tags": [ "home", "green" ]
}

そのスキーマは次のように表現される：

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/product.schema.json",
  "title": "Product",
  "description": "A product from Acme's catalog",
  "type": "object",
  "properties": {
    "productId": {
      "description": "The unique identifier for a product",
      "type": "integer"
    },
    "productName": {
      "description": "Name of the product",
      "type": "string"
    },
    "price": {
      "description": "The price of the product",
      "type": "number",
      "exclusiveMinimum": 0
    },
    "tags": {
      "description": "Tags for the product",
      "type": "array",
      "items": {
        "type": "string"
      },
      "minItems": 1,
      "uniqueItems": true
    }
  },
  "required": [ "productId", "productName", "price" ]
}

（参考ページより引用）

第1階層にはスキーマそのもののメタ情報（$schema、$id、titleなど）と、ルートとなるデータ型（type）。
第2階層（propertiesのプロパティ）にはオブジェクトのプロパティの定義情報。プロパティのデータ型もまたobjectの場合は入れ子構造でプロパティの定義情報が記述される。

参考ページ

データ型＋α の表現力

JSON SchemaはJSONの仕様に定められたJSONのデータ型について記述することはもちろん、それらが特定のJSONデータにおいてどのように構造化されているかを定義。
さらにJSON仕様だけでは表現できないごとにさまざまなデータの制約も表現できる。

例えば、

型	型固有のキーワード	説明
array	items, minItems, maxItems, uniqueItems	要素のスキーマ定義、要素数の制約、要素の一意性など
number	minimum, maximum, exclusiveMinimum, exclusiveMaximum, multipleOf	数値の範囲、倍数制限など
object	required, properties, patternProperties, minProperties, maxProperties	必須プロパティ、入れ子のプロパティ、正規表現によるプロパティマッチング、プロパティ数の制約など
string	minLength, maxLength, pattern, format	文字列長の制限、正規表現による制約、所定のフォーマットへの適合など

参考ページ

Type-specific Keywords

JSONらしい柔軟な構造定義

JSONの特性はそのシンプルさと柔軟性。後者はメリットにもデメリットにもなる。アプリケーション間でJSONデータのやり取りするとき「存在する想定でいたプロパティが存在しない」「プロパティの型が想定していたものではない」といった問題が生じうる。

JSON Schemaにはこの「柔軟性」を定義するための構文やキーワードも存在。
例えば、

構文・キーワード	説明
`"type": ["type1", "type2", ...]`	いずれかのデータ型に該当する
`"anyOf": [{ ... }, ...]`	サブスキーマのいずれかに該当する
`"not": {...}`	サブスキーマに該当しない
`required`	指定したプロパティが必ず存在する
`dependentrequired`	プロパティAが存在する場合、別のプロパティBやCも存在する
`"if": {...}, "then": {...},"else": {...}`	条件として指定したサブスキーマにマッチする場合としない場合とで、それぞれ別のサブスキーマにマッチするかを検証

nullもデータ型の1つである点に注意！ null値を取りうるプロパティはそのことをきちんとスキーマに表現する必要がある。"type": "string"ではなく "type": ["string", "null"]でないといけないということ。

参考ページ

さらに高度な検証

ここまでざっと見てきた以外にも、条件付きのスキーマ検証の定義や、取りうる値を列挙型や定数として制約、日時・日付・時刻・Eメールといったフォーマットの定義など、さらに高度な検証の助けとなる仕様も存在する。

参考ページ