JSON スキーマを使用したアダプティブフォームの作成

前提条件

フォームモデルとして JSON スキーマを使用してアダプティブフォームをオーサリングする場合、JSON スキーマの基本を理解している必要があります。この記事を読む前に次のコンテンツを読んでおくことをお勧めします。

フォームモデルとしての JSON スキーマの使用

AEM Forms では、既存の JSON スキーマをフォームモデルとして使用したアダプティブフォームの作成がサポートされています。JSON スキーマは、組織のバックエンドシステムによりデータの生成や消費が行われる構造を表しています。使用するJSONスキーマは、v4仕様に準拠している必要があります。

JSON スキーマの使用の主な特長は、次のとおりです。

JSON の構造は、アダプティブフォームのオーサリングモードの「コンテンツファインダー」タブでツリーとして表示されます。JSON 階層からアダプティブフォームに要素をドラッグして追加できます。
関連付けられたスキーマに準拠する JSON を使用して、フォームに事前入力できます。
ユーザーが入力したデータは、送信時には関連付けられたスキーマに適合する JSON として送信されます。

JSON スキーマは、単純型要素と複合型要素で構成されています。要素には、その要素にルールを追加する属性が含まれています。これらの要素や属性がアダプティブフォーム上にドラッグされると、自動的に該当するアダプティブフォームコンポーネントにマッピングされます。

JSON 要素とアダプティブフォームコンポーネントのマッピングは、次のように行われます。

JSON の要素、プロパティ、属性	アダプティブフォームコンポーネント
enum制約とenumNames制約を含む文字列プロパティ。構文, `{` `"type" : "string",` `"enum" : ["M", "F"]` `"enumNames" : ["Male", "Female"]` `}`	ドロップダウンコンポーネント： enumNames にリストされた値はドロップボックスに表示されます。 enum にリストされた値は計算に使用されます。
フォーマット制限付きの文字列プロパティ。例えば、電子メール、日付など。構文, `{` `"type" : "string",` `"format" : "email"` `}`	タイプが文字列でフォーマットが電子メールのときに、電子メールのコンポーネントがマップされます。タイプが文字列でフォーマットがホスト名のときに、検証付きテキストボックスのコンポーネントがマップされます。
{ "type" : "string", }	テキストフィールド
number プロパティ	サブタイプが float に設定された数値フィールド
integer プロパティ	サブタイプが integer に設定された数値フィールド
boolean プロパティ	切り替え
object プロパティ	パネル
array プロパティ	minItems および maxItems にそれぞれ等しい min および max を持つ繰り返し可能なパネル。同種の配列のみがサポートされます。したがって、項目制約は配列ではなくオブジェクトでなければなりません。

共通のスキーマプロパティ

アダプティブフォームは JSON スキーマで使用可能な情報を使用して、生成された各フィールドをマッピングします。具体的には、次のことを実行します。

titleプロパティは、アダプティブフォームコンポーネントのラベルとして機能します。
descriptionプロパティは、アダプティブフォームコンポーネントの詳細な説明として設定されます。
defaultプロパティは、アダプティブフォームフィールドの初期値として機能します。
maxLengthプロパティは、テキストフィールドコンポーネントのmaxlength属性として設定されます。
minimum、maximum、exclusiveMinimumおよびexclusiveMaximumプロパティは、数値ボックスコンポーネントに使用されます。
DatePickerコンポーネントの範囲をサポートするために、minDateとmaxDateの追加のJSONスキーマプロパティが用意されています。
minItemsプロパティとmaxItemsプロパティは、パネルコンポーネントに追加または削除できる項目/フィールドの数を制限するために使用します。
readOnlyプロパティは、アダプティブフォームコンポーネントの読み取り専用属性を設定します。
requiredプロパティはアダプティブフォームフィールドを必須としてマークしますが、typeがobjectの場合は最後の送信JSONデータのフィールドはそのオブジェクトに対応する空の値を持ちます。
patternプロパティは、アダプティブフォームで検証パターン(正規式)として設定されます。
JSONスキーマファイルの拡張子は。スキーマ.jsonにする必要があります。例えば、<filename>.スキーマ.jsonのように指定します。

JSON スキーマのサンプル

JSON スキーマの例を示します。

{
 "$schema": "https://json-schema.org/draft-04/schema#",
 "definitions": {
  "employee": {
   "type": "object",
   "properties": {
    "userName": {
     "type": "string"
    },
    "dateOfBirth": {
     "type": "string",
     "format": "date"
    },
    "email": {
     "type": "string",
     "format": "email"
    },
    "language": {
     "type": "string"
    },
    "personalDetails": {
     "$ref": "#/definitions/personalDetails"
    },
    "projectDetails": {
     "$ref": "#/definitions/projectDetails"
    }
   },
   "required": [
    "userName",
    "dateOfBirth",
    "language"
   ]
  },
  "personalDetails": {
   "type": "object",
   "properties": {
    "GeneralDetails": {
     "$ref": "#/definitions/GeneralDetails"
    },
    "Family": {
     "$ref": "#/definitions/Family"
    },
    "Income": {
     "$ref": "#/definitions/Income"
    }
   }
  },
  "projectDetails": {
   "type": "array",
   "items": {
    "properties": {
     "name": {
      "type": "string"
     },
     "age": {
      "type": "number"
     },
     "projects": {
      "$ref": "#/definitions/projects"
     }
    }
   },
   "minItems": 1,
   "maxItems": 4
  },
  "projects": {
   "type": "array",
   "items": {
    "properties": {
     "name": {
      "type": "string"
     },
     "age": {
      "type": "number"
     },
     "projectsAdditional": {
      "$ref": "#/definitions/projectsAdditional"
     }
    }
   },
   "minItems": 1,
   "maxItems": 4
  },
  "projectsAdditional": {
   "type": "array",
   "items": {
    "properties": {
     "Additional_name": {
      "type": "string"
     },
     "Additional_areacode": {
      "type": "number"
     }
    }
   },
   "minItems": 1,
   "maxItems": 4
  },
  "GeneralDetails": {
   "type": "object",
   "properties": {
    "age": {
     "type": "number"
    },
    "married": {
     "type": "boolean"
    },
    "phone": {
     "type": "number",
     "aem:afProperties": {
      "sling:resourceType": "/libs/fd/af/components/guidetelephone",
      "guideNodeClass": "guideTelephone"
     }
    },
    "address": {
     "type": "string"
    }
   }
  },
  "Family": {
   "type": "object",
   "properties": {
    "spouse": {
     "$ref": "#/definitions/spouse"
    },
    "kids": {
     "$ref": "#/definitions/kids"
    }
   }
  },
  "Income": {
   "type": "object",
   "properties": {
    "monthly": {
     "type": "number"
    },
    "yearly": {
     "type": "number"
    }
   }
  },
  "spouse": {
   "type": "object",
   "properties": {
    "name": {
     "type": "string"
    },
    "Income": {
     "$ref": "#/definitions/Income"
    }
   }
  },
  "kids": {
   "type": "array",
   "items": {
    "properties": {
     "name": {
      "type": "string"
     },
     "age": {
      "type": "number"
     }
    }
   },
   "minItems": 1,
   "maxItems": 4
  }
 },
 "type": "object",
 "properties": {
  "employee": {
   "$ref": "#/definitions/employee"
  }
 }
}

再使用可能なスキーマ定義

定義キーを使用して再使用可能なスキーマを識別します。フラグメントの作成には、再利用可能なスキーマ定義が使用されます。これは、XSD での複合型の識別と同じです。定義付きの JSON スキーマのサンプルは以下のとおりです。

{
  "$schema": "https://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"]
    }
  },
 
  "type": "object",
 
  "properties": {
    "billing_address": { "$ref": "#/definitions/address" },
    "shipping_address": { "$ref": "#/definitions/address" }
  }
}

上記の例では、それぞれの顧客が出荷先と請求先のどちらの住所もある場合の顧客レコードを定義します。どちらの住所も構造（都道府県、市区町村、番地など）が同じ場合は、住所が重複しないようにすることをお勧めします。また、今後変更が行われたときに、簡単にフィールドを追加したり削除したりできます。

JSON スキーマ定義におけるフィールドの事前構成

aem:afPropertiesプロパティを使用して、JSONスキーマフィールドを事前設定し、カスタムアダプティブフォームコンポーネントにマップすることができます。以下に例を示します。

{
    "properties": {
        "sizeInMB": {
            "type": "integer",
            "minimum": 16,
            "maximum": 512,
            "aem:afProperties" : {
                 "sling:resourceType" : "/apps/fd/af/components/guideTextBox",
                 "guideNodeClass" : "guideTextBox"
             }
        }
    },
    "required": [ "sizeInMB" ],
    "additionalProperties": false
}

アダプティブフォームコンポーネントで許容される値の制限

JSONスキーマ要素に次の制限を追加して、アダプティブフォームコンポーネントに許容される値を制限することができます。

スキーマプロパティ	データタイプ	説明	コンポーネント
`maximum`	String	数値および日付の上限を指定します。デフォルトでは、最大値が含まれます。	数値ボックス数値ステッパー日付選択
`minimum`	文字列	数値および日付の下限を指定します。デフォルトでは、最小値が含まれます。	数値ボックス数値ステッパー日付選択
`exclusiveMaximum`	Boolean	true の場合、フォームのコンポーネントで指定された数値または日付は、maximum プロパティに指定された数値または日付よりも小さい値である必要があります。 false の場合、フォームのコンポーネントで指定された数値または日付は、maximum プロパティに指定された数値または日付以下の値である必要があります。	数値ボックス数値ステッパー日付選択
`exclusiveMinimum`	ブール値	true の場合、フォームのコンポーネントで指定された数値または日付は、minimum プロパティに指定された数値または日付よりも大きい値である必要があります。 false の場合、フォームのコンポーネントで指定された数値または日付は、minimum プロパティに指定された数値または日付以上の値である必要があります。	数値ボックス数値ステッパー日付選択
`minLength`	文字列	コンポーネントで許可される最小文字数を指定します。最小の長さは 0 以上である必要があります。	テキストボックス
`maxLength`	文字列	コンポーネントで許可される最大文字数を指定します。最大の長さは 0 以上である必要があります。	テキストボックス
`pattern`	文字列	文字のシーケンスを指定します。文字が指定されたパターンに適合すると、コンポーネントはその文字を受け入れます。この pattern プロパティは、対応するアダプティブフォームコンポーネントの検証パターンにマッピされます。	XSDスキーマにマップされているすべてのアダプティブフォームコンポーネント
maxItems	文字列	配列の項目の最大数を指定します。項目の最大数は 0 以上である必要があります。
minItems	文字列	配列の項目の最小数を指定します。項目の最小数は 0 以上である必要があります。