生成エンドポイントのスキーマファイルのコンフィギュレーション

1 つ以上のスキーマが列挙される definitions セクションが、スキーマファイルにあります。各スキーマは、API リソースを構築するために使用されます。スキーマごとに、以下の属性が指定されます。

• title と description：API 定義ドキュメントで使用されます。
• リソースの type：通常は object に設定されます。
• properties のリスト。各プロパティに以下が含まれています。
  • title と description：API 定義ドキュメントで使用されます。
  • type：プロパティの JSON データ型を定義します（スカラー値の場合）。
  • ref：プロパティの URI 参照を定義します（タイプキーなどの複合値の場合）。
  • プロパティの業務機能に必要なオプション属性。

例えば、ベースコンフィギュレーションの Activity リソースでスキーマの部分を以下に示します。

"Activity": {
  "title": "Activity",
  "description": "An `Activity` is an assignable item that represents a task to be done, a decision to be made, or information to be aware of",
  "type": "object",
  "properties": {
    "activityPattern": {
      "title": "Activity pattern",
      "description": "The code of the `ActivityPattern` used to create this activity and set its initial values",
      "type": "string"
      ...
      }
    },

ベースコンフィギュレーションには、API 固有の拡張スキーマファイルのセットが含まれています。これらのファイルの目的は、特定の API 用のカスタムリソースに関するスキーマ情報を定義することです。「<API>_ext-1.0.schema.json」のパターンを使用してこれらのファイルに名前が付けられます。<API> は API の内部名です。例えば、common_ext-1.0.schema.json ファイルを使用して、Common API でカスタムリソースに関するスキーマ情報を定義します。拡張スキーマファイルには、Studio で integration -> schemas -> ext -> <API>.v1 ノードを介してアクセスできます

カスタムエンティティ用のエンドポイントを生成すると、REST エンドポイントジェネレータが以下のコードを関連の拡張スキーマファイルに追加します。

    "<resourceName>": {
      "title": "<custom entity name>",
      "description": "<custom entity name>",
      "type": "object",
      "properties": {
        // TODO RestEndpointGenerator : Add schema properties here
        "id": {
          "title": "ID",
          "description": "The unique identifier of this element",
          "type": "string",
          "readOnly": true
        }
      }
    }

例えば、CustomEntity_Ext エンティティ用のエンドポイントを生成すると、以下が拡張スキーマ ファイルに追加されます。

    "CustomEntityExt": {
      "title": "Custom entity ext",
      "description": "Custom entity ext",
      "type": "object",
      "properties": {
        // TODO RestEndpointGenerator : Add schema properties here
        "id": {
          "title": "ID",
          "description": "The unique identifier of this element",
          "type": "string",
          "readOnly": true
        }
      }
    }

REST エンドポイントジェネレータでは、唯一のプロパティ（id）に関する properties 情報だけを提供します。開発者は以下の作業を担当します。

• カスタムエンティティでエンドポイントが利用できる必要があるフィールドの決定。
• これらのフィールドに関するマッパー情報の追加。

例えば、CustomEntity_Ext エンティティに次の 3 つのフィールドがあるとします。

• CustomDescription（文字列型）
• IsActive（Boolean 型）
• ExpirationDate（日付時刻型）

CustomDescription と IsActive を GET、POST、または PATCH で使用できる必要があることを開発者が決定します。以下の太字で示されているコードを開発者は追加する必要があります。

    "CustomEntityExt": {
      "title": "Custom entity ext",
      "description": "Custom entity ext",
      "type": "object",
      "properties": {
        // TODO RestEndpointGenerator : Add schema properties here
        "id": {
          "title": "ID",
          "description": "The unique identifier of this element",
          "type": "string",
          "readOnly": true
        },
        "customDescription": {
          "title": "CustomDescription",
          "description": "The description for the CustomEntity",
          "type": "string"
        },
        "id": {
          "title": "isActive",
          "description": "Whether the CustomEntity is active",
          "type": "boolean"
        }
      }
    }

また、ExpirationDate を GET と POST/PATCH 応答で使用禁止にする必要があることを開発者が決定します。そのため、このフィールドがスキーマから省略されます。

各プロパティのデータ型は、type 属性または $ref 属性を使用して指定します。

  "definitions": {
    "CustomEntityExt": {
      "title": "Custom entity ext",
      "description": "Custom entity ext",
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "isActive": {
          "type": "boolean"
        },
        "customDescription": {
          "type": "string"
        },
        "expirationDate": {
          "type": "string",
          "format": "date-time"
        }
      }
    }
  }

    "assignmentStatus": {
      "code": "pendingassignment",
      "name": "Pending Assignment"
    },

"assignmentStatus": {
  ... 
  "$ref": "#/definitions/TypeKeyReference",
  "x-gw-extensions": {
    "typelist": "AssignmentStatus"
  }

"spatialPoint": {
  ... 
  "$ref": "#/definitions/SpatialPoint"
}

スキーマファイルでは、type 属性または $ref 属性のいずれかを使用して各プロパティのデータ型を指定する必要があります。また、オプション属性を追加することもできます。一部の属性は、プロパティの直接の子です。それ以外の属性は、x-gw-extensions オブジェクト内で宣言する必要があります。

一部の属性にはデフォルト値があります。以下の表は、デフォルト値を示します。

"x-gw-nullable": false

"x-gw-sinceVersion": "1.​1.​0"

  "definitions": {
    "CustomEntityExt": {
      ...
      "properties": {
        ...
        },
        "expirationDate": {
          "type": "string",
          "format": "date-time",
          "readOnly": true,
          "x-gw-sinceVersion": "1.1.0"
        }
        ...

  "definitions": {
    "CustomEntityExt": {
      ...
      "properties": {
        ...
        },
        "severityType": {
          "$ref": "#/definitions/TypeKeyReference",
          "x-gw-extensions": {
            "typelist": "SeverityType",
            "createOnly": true,
            "requiredForCreate": true,
            "filterable": true,
            "sortable": true
          }
        }
        ...

  "definitions": {
    "CustomEntityExt": {
      ...
      "properties": {
        ...
        },
        "customDescription": {
          "type": "string",
          "x-gw-nullable": false,
          "x-gw-extensions": {
            "requiredForCreate": true
          }
        }
        ...