JSON Module を使用した JSON スキーマに対するドキュメントの検証

JSON Module の Validate schema 操作 (<json:validate-schema>) は、入力コンテンツが指定した JSON スキーマに準拠していることを検証します。

サポートされるスキーマバージョンは、Draft 3、Draft 4、Draft 6、Draft 7、Draft 2019-09、Draft 2020-12 です。
大量の JSON ファイルを読み込むと、操作でメモリの制約が発生する可能性があります。

Studio で Validate Schema 操作設定する

Validate schema 操作は、メッセージペイロードレベルで入力ドキュメントを検索します。ただし、独自の入力を行うこともできます。スキーマコンテンツを検証するには、スキーマとスキーマコンテンツの両方ではなくいずれかのみを指定します。[Schema (スキーマ)] 項目でファイルをアップロードするか、[Schema content (スキーマコンテンツ)] 項目でダイレクトスキーマテキストコンテンツを手動で追加できます。次の例は、Anypoint Studio で操作を設定する方法を示しています。

Studio のフローで、[File Read] 操作をキャンバスにドラッグします。
[Path (パス)] を document.json に設定します。
[Target (対象)] を jsonDoc に設定します。
[Validate schema] 操作を [Read] 操作の横側にドラッグします。
[Schema (スキーマ)] を /schema/my-schema.json に設定します。

設定 XML エディターでは、<json:validate-schema> 設定は次のように記述されます。

<flow name="process">
    <file:read path="document.json" target="jsonDoc" />
    <json:validate-schema schema="/schema/my-schema.json">
    </json:module:validate-schema>
</flow>

Validation Module の All 操作 (<validation:all>) 内で Validate schema 操作 (<json:validate-schema>) を使用できます。

スキーマコンテンツを設定する

次の例では、Validate schema 操作の [Schema Content (スキーマコンテンツ)] 項目を設定します。この項目に、検証するスキーマテキストコンテンツを入力します。

スキーマコンテンツを追加するには、スキーマとスキーマコンテンツの両方ではなくいずれかのみを指定します。[Schema (スキーマ)] 項目でファイルをアップロードするか、[Schema content (スキーマコンテンツ)] 項目でダイレクトスキーマテキストコンテンツを手動で追加できます。

Studio で、フローから [Validate Schema] 操作を選択します。
[Schema Content (スキーマコンテンツ)] 項目に、次のようなに検証するコンテンツを入力します。

{
   “$schema”: “http://json-schema.org/draft-04/schema#”,
   “type”: “array”,
   “items”: {
    “type”: “object”,
    “properties”: {
     “a”: {
      “type”: “string”,
      “minLength”: 0,
      “maxLength”: 255
      },
     “b”: {
      “type”: “string”,
      “minLength”: 0,
      “maxLength”: 255
     }
    },
    “not”: {“required”:[“c”]}
   }
  }

検証するスキーマコンテンツが設定された [Schema content (スキーマコンテンツ)] 項目

検証エラーの処理

検証に成功した場合はフローの次の操作に進みます。検証に失敗すると、Mule アプリケーションから JSON:SCHEMA_NOT_HONOURED エラーが返されます。入力 JSON ドキュメントがそのスキーマに準拠していないなど、検証に失敗する理由はさまざまです。エラーの説明には、オブジェクトの JSON 配列が含まれます。これらのオブジェクトごとに、検出された各エラーに関する情報が含まれます。

たとえば、次の JSON 入力があるとします。

無効な JSON

[
  {"a": "", "b": ""},
  {"a": "", "b": ""},
  {"a":""},
  {"a": "", "b":""},
  {"b": ""}
]

そして、JSON スキーマが次のとおりであるとします。

JSON スキーマ

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "a": {
        "type": "string",
		"minLength": 1,
		"maxLength": 255
		},
      "b": {
        "type": "string",
		"minLength": 1,
		"maxLength": 255
      }
    },
    "required": ["a", "b"]
  }
}

a と b のどちらの文字列属性も必須であるため ("required": ["a", "b"])、この入力 JSON は無効です。どちらの文字列属性も 1 文字以上にする必要があります。

JSON Module では、検証エラーの配列を返す詳細なエラー応答が提供されます。また、検証に失敗した場合、次のように File Write 操作を使用してレポートをファイルに追加できます。

<flow name="validate">
    <try>
        <json:validate-schema schema="/schema/object-array-schema.json" />
        <error-handler>
            <on-error-propagate type="JSON:SCHEMA_NOT_HONOURED">
                <file:write config-ref="file" path="errors/jsonSchemas.json" mode="APPEND">
                    <file:content>#[error.errorMessage.payload]</file:content>
                </file:write>
            </on-error-propagate>
        </error-handler>
    </try>
</flow>

次の JSON コンテンツには、レポートファイルに追加される検証エラーの配列が表示されています。

[ {
  "level" : "error",
  "schema" : {
    "loadingURI" : "file:/schema/object-array-schema.json#",
    "pointer" : "/items/properties/a"
  },
  "instance" : {
    "pointer" : "/0/a"
  },
  "domain" : "validation",
  "keyword" : "minLength",
  "message" : "string \"\" is too short (length: 0, required minimum: 1)",
  "value" : "",
  "found" : 0,
  "minLength" : 1
}, {
  "level" : "error",
  "schema" : {
    "loadingURI" : "file:/schema/object-array-schema.json#",
    "pointer" : "/items/properties/b"
  },
  "instance" : {
    "pointer" : "/0/b"
  },
  "domain" : "validation",
  "keyword" : "minLength",
  "message" : "string \"\" is too short (length: 0, required minimum: 1)",
  "value" : "",
  "found" : 0,
  "minLength" : 1
}, {
  "level" : "error",
  "schema" : {
    "loadingURI" : "file:/schema/object-array-schema.json#",
    "pointer" : "/items/properties/a"
  },
  "instance" : {
    "pointer" : "/1/a"
  },
  "domain" : "validation",
  "keyword" : "minLength",
  "message" : "string \"\" is too short (length: 0, required minimum: 1)",
  "value" : "",
  "found" : 0,
  "minLength" : 1
}, {
  "level" : "error",
  "schema" : {
    "loadingURI" : "file:/schema/object-array-schema.json#",
    "pointer" : "/items/properties/b"
  },
  "instance" : {
    "pointer" : "/1/b"
  },
  "domain" : "validation",
  "keyword" : "minLength",
  "message" : "string \"\" is too short (length: 0, required minimum: 1)",
  "value" : "",
  "found" : 0,
  "minLength" : 1
}, {
  "level" : "error",
  "schema" : {
    "loadingURI" : "file:/schema/object-array-schema.json#",
    "pointer" : "/items"
  },
  "instance" : {
    "pointer" : "/2"
  },
  "domain" : "validation",
  "keyword" : "required",
  "message" : "object has missing required properties ([\"b\"])",
  "required" : [ "a", "b" ],
  "missing" : [ "b" ]
}, {
  "level" : "error",
  "schema" : {
    "loadingURI" : "file:/schema/object-array-schema.json#",
    "pointer" : "/items/properties/a"
  },
  "instance" : {
    "pointer" : "/2/a"
  },
  "domain" : "validation",
  "keyword" : "minLength",
  "message" : "string \"\" is too short (length: 0, required minimum: 1)",
  "value" : "",
  "found" : 0,
  "minLength" : 1
}, {
  "level" : "error",
  "schema" : {
    "loadingURI" : "file:/schema/object-array-schema.json#",
    "pointer" : "/items/properties/a"
  },
  "instance" : {
    "pointer" : "/3/a"
  },
  "domain" : "validation",
  "keyword" : "minLength",
  "message" : "string \"\" is too short (length: 0, required minimum: 1)",
  "value" : "",
  "found" : 0,
  "minLength" : 1
}, {
  "level" : "error",
  "schema" : {
    "loadingURI" : "file:/schema/object-array-schema.json#",
    "pointer" : "/items/properties/b"
  },
  "instance" : {
    "pointer" : "/3/b"
  },
  "domain" : "validation",
  "keyword" : "minLength",
  "message" : "string \"\" is too short (length: 0, required minimum: 1)",
  "value" : "",
  "found" : 0,
  "minLength" : 1
}, {
  "level" : "error",
  "schema" : {
    "loadingURI" : "file:/schema/object-array-schema.json#",
    "pointer" : "/items"
  },
  "instance" : {
    "pointer" : "/4"
  },
  "domain" : "validation",
  "keyword" : "required",
  "message" : "object has missing required properties ([\"a\"])",
  "required" : [ "a", "b" ],
  "missing" : [ "a" ]
}, {
  "level" : "error",
  "schema" : {
    "loadingURI" : "file:/schema/object-array-schema.json#",
    "pointer" : "/items/properties/b"
  },
  "instance" : {
    "pointer" : "/4/b"
  },
  "domain" : "validation",
  "keyword" : "minLength",
  "message" : "string \"\" is too short (length: 0, required minimum: 1)",
  "value" : "",
  "found" : 0,
  "minLength" : 1
} ]

スキーマのリダイレクト

JSON スキーマの中には、公開 URI を介して他のスキーマを参照するものがあります。けれども、主としてパフォーマンスやセキュリティ上の理由から、これらのスキーマをインターネットから取得したくないことがあります。

この問題の解決法は、メインスキーマと参照スキーマをすべてアプリケーションに含めることです。ただし、この解決法によって新たな問題が生じます。元のスキーマに、公開スキーマではなく、ローカルスキーマをポイントさせる必要があることです。

この問題に対処するために、このモジュールではスキーマのリダイレクトという概念が導入され、スキーマ自体を変更しなくても、外部参照をローカル参照に置換することができます。

<flow name="process">
    <json:validate-schema schema="/schema/my-schema.json">
        <json:schema-redirects>
            <json:schema-redirect from="http://mule.org/schemas/fstab.json" to="schema/fstab.json"/>
        </json:schema-redirects>
    </json:validate-schema>
</flow>

上記の例では、http://mule.org/schemas/fstab.json のスキーマが、アプリケーション内に付属する、schema/fstab.json というパスのスキーマにリダイレクトされます。

追加オプション

バリデーターには、重複キーを許可するかどうか、参照解決をどのように処理するかなどの追加オプションがあります。

詳細は、「JSON Module ドキュメントリファレンス」を参照してください。

ガートナーが MuleSoft をリーダーとして評価

Salesforce のフルパワーを解放する API 活用術

Anypoint Platform：開発基礎 (無料)

MuleSoft Forum Japan