JSON スキーマの型の再利用

JSON スキーマは、特定のアプリケーションで必要な JSON データの形式とそのやりとりの方法を提供する標準です。多くの既存のデータ形式または型は、この標準を使用して表されます。具体的な例を挙げると、RAML ファイルで記述される REST API の型は JSON スキーマで定義されることが多いです。

定義済みの型を再利用するには、JSON スキーマを DataWeave に読み込み、各自のスクリプトで型構造を使用できるようにします。

JSON スキーマローダーは、 JSON スキーマの Draft 7ˆ Leaving the Site を使用してスキーマを解析します。

JSON スキーマの型のインポート

次の例は、リソースディレクトリの JSON スキーマ (Person.json) を示しています。

JSON スキーマ (example/schema/Person.json):

{
  "$id": "https://example.com/person.schema.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Person",
  "type": "object",
  "properties": {
    "firstName": {
      "type": "string",
      "description": "The person's first name."
    },
    "lastName": {
      "type": "string",
      "description": "The person's last name."
    },
    "age": {
      "description": "Age in years, which must be equal to or greater than zero.",
      "type": "integer",
      "minimum": 0
    }
  },
  "required": ["firstName", "lastName"]
}JSON

次の例は、JSON スキーマローダーを使用して型をインポートする方法を示しています。

DataWeave スクリプトヘッダー:

import * from jsonschema!example::schema::Person

インポート構文

JSON スキーマの型をインポートするには、以下の構文を使用します。

typeToImport: * を単独で使用してスキーマで定義されているすべての型をインポートしたり、スキーマの 1 つの型 (Root など) をインポートしたりできます。異なる名前の JSON スキーマの型 (Root as Person など) をインポートすることもできます。これにより、スクリプトでその名前を使用して型を参照できます。
pathToJsonSchema: スキーマファイルへのパスを指定するには、ファイルの区切り文字を :: に置き換えて、ファイル名の .json 拡張子を削除します。たとえば、スキーマへのパスが example/schema/Person.json の場合、example::schema::Person を使用します。

import _typesToImport_ from jsonschema!_pathToJsonSchema_

次の例は、型をインポートする方法を示しています。

import * from jsonschema!example::schema::Person

DataWeave スクリプトでの型の使用

上記の例のインポートディレクティブをスクリプトヘッダーに含めると、JSON スキーマの既存のすべての型が読み込まれます。import * from jsonschema!example::schema::Person の既存の型は、ルートで指定されている Root 型のみです。この型では、3 つのプロパティ (firstName、lastName、age) を含めることができるオブジェクトが記述されています。これは、DataWeave スクリプトで次の型を宣言することに相当します。

DataWeave スクリプト:

%dw 2.0
type Root = { firstName: String, lastName: String, age?: Number }dataweave

age は、唯一の省略可能な項目 (? で示される) になります。

型を使用して、値が JSON スキーマで定義された構造に従っているかどうかを判断できます。次の例では、オブジェクトに必須項目 firstName および lastName が含まれているため、値 true が出力されます。

DataWeave スクリプト:

%dw 2.0
import * from jsonschema!jsonschema!example::schema::Person
---
{
 firstName: "John",
 lastName: "Doe"
} is Rootdataweave

出力:

"true"

次の例では、オブジェクトに必須項目 firstName および lastName が含まれていないため、値 false が出力されます。

DataWeave スクリプト:

%dw 2.0
import * from jsonschema!jsonschema!example::schema::Person
---
{
 firstName: "John",
 age: 20
} is Rootdataweave

出力:

"false"

スキーマ内の定義の使用

DataWeave は、モジュールのインポート時に JSON スキーマ内の定義を読み込みます。

JSON スキーマ (example/schema/Account.json):

{
 "$schema": "http://json-schema.org/draft-04/schema#",
 "definitions": {
   "address": {
     "type": "object",
     "properties": {
       "street_address": {
         "type": "string"
       },
       "city": {
         "type": "string"
       },
       "state": {
         "type": "string"
       }
     },
     "required": [
       "street_address",
       "city",
       "state"
     ]
   },
   "person": {
     "type": "object",
     "properties": {
       "firstName": {
         "type": "string",
         "description": "The person's first name."
       },
       "lastName": {
         "type": "string",
         "description": "The person's last name."
       },
       "age": {
         "description": "Age in years, which must be equal to or greater than zero.",
         "type": "integer",
         "minimum": 0
       }
     },
     "required": [
       "firstName",
       "lastName"
     ]
   }
 },
 "type": "object",
 "properties": {
   "person": {
     "$ref": "#/definitions/person"
   },
   "address": {
     "$ref": "#/definitions/address"
   }
 }
}JSON
コンテンツを展開する

次のディレクティブを使用して、そのスキーマの型をインポートできます。

import * from jsonschema!example::schema::Account

スキーマで定義された型には、次の型の宣言と同じ効果があります。

type Root = { address?: address, person?: person }

type address = { street_address: String, city: String, state: String }

type person = { firstName: String, lastName: String, age?: Number }

インポートディレクティブを使用して、スキーマの 1 つの型をインポートします。

import address from jsonschema!example::schema::Account

型名の競合を回避するために、as キーワードを使用して、インポートされた型名を別の名前に変更できます。

import address as Account_Address from jsonschema!example::schema::Account

パターン一致での使用の促進

JSON スキーマからインポートされた型を使用して、特定の型の入力である場合に特定のアクションを実行できます。これらのインポートされた型は、パターン一致で役立ちます。

次の例では、値 person が出力されます (オブジェクトでその型定義がインポートされるため)。

DataWeave スクリプト:

%dw 2.0
import * from jsonschema!example::schema::Account
---
{
 firstName: "John",
 lastName: "Doe"
} match {
case is person -> "PERSON"
case is address -> "ADDRESS"
else -> "NO TYPE MATCHED"
}dataweave

出力:

"PERSON"

次の例では、値 address が出力されます (オブジェクトでその型定義がインポートされるため)。

DataWeave スクリプト:

%dw 2.0
import * from jsonschema!example::schema::Account
---
{
 street_address: "742 Evergreen Terrace",
 city: "Gotham",
 State: "OH"
} match {
case is person -> "PERSON"
case is address -> "ADDRESS"
else -> "NO TYPE MATCHED"
}dataweave

出力:

"ADDRESS"

組み込みの JSON スキーマの型

DataWeave は、DataWeave 型に変換される次の JSON スキーマ型をサポートしています。

JSON スキーマ型 DataWeave 型

JSON スキーマ型	DataWeave 型
`number`	`Number`
`integer`	`Number`
`string`	`String`
`boolean`	`Boolean`
`array`	`Array`
`enum`	`Union`
`null`	`Null`
`object`	`Object`

number

Number

integer

Number

string

String

boolean

Boolean

array

Array

enum

Union

null

Null

object

Object

制限事項

DataWeave は、JSON スキーマ文字列型の形式をサポートしておらず、検証や制限なしにこれらの型を String に変換します。
DataWeave は、最大値や最小値などの数値型に対する制限をサポートしておらず、検証や制限なしでこれらの型を Number に変換します。
DataWeave は、パターンをサポートしていません。

オブジェクト種別

DataWeave は、JSON スキーマオブジェクト種別の必須ではないプロパティを、DataWeave オブジェクト種別の省略可能なプロパティとしてマークします。

次の例では、DataWeave 型を出力します。

JSON スキーマ:

{
  "type": "object",
  "properties": {
    "name":      { "type": "string" },
    "email":     { "type": "string" },
    "address":   { "type": "string" },
    "telephone": { "type": "string" }
  },
  "required": ["name", "email"]
}JSON

出力:

%dw 2.0
type Root = { address?: String, name: String, telephone?: String, email: String }dataweave

追加プロパティが許可される場合、DataWeave はオープンオブジェクト定義を生成します。

次の例では、DataWeave 型を出力します。

JSON スキーマ:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "number":      { "type": "number" },
    "street_name": { "type": "string" },
    "street_type": { "type": "string",
      "enum": ["Street", "Avenue", "Boulevard"]
    }
  },
  "required": ["number"],
  "additionalProperties": true
}JSON

出力:

%dw 2.0
type Root = { number: Number, street_type?: "Street" | "Avenue" | "Boulevard", street_name?: String }dataweave

逆に、追加プロパティが許可されない場合、DataWeave はクローズドオブジェクト定義を生成します。

次の例では、DataWeave 型を出力します。

JSON スキーマ:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "number":      { "type": "number" },
    "street_name": { "type": "string" },
    "street_type": { "type": "string",
      "enum": ["Street", "Avenue", "Boulevard"]
    }
  },
  "required": ["number"],
  "additionalProperties": false
}JSON

出力:

%dw 2.0
type Root = {| number: Number, street_type?: "Street" | "Avenue" | "Boulevard", street_name?: String |}dataweave

サブスキーマキーワードの組み込み JSON スキーマサポート

JSON スキーマでサブスキーマキーワードを使用すると、提供されたサブスキーマに基づいて複合型が生成されます。

JSON スキーマキーワード DataWeave 型

JSON スキーマキーワード	DataWeave 型
`allOf`	`Intersection`
`anyOf`	`Union`
`oneOf`	`Union`

allOf

Intersection

anyOf

Union

oneOf

Union

次の例では、DataWeave 型を出力します。 .JSON スキーマ:

{
  "anyOf": [
    { "type": "string" },
    { "type": "number" }
  ]
}JSON

出力:

%dw 2.0
type Root = (String | Number)dataweave