> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.itential.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server. # Schema field definitions > Reference for all fields available in adapter schema files, including general, security, and required field definitions. Schema files follow the JSON schema specification with additional adapter-specific fields. Any construct that is valid in JSON schema is also valid in an adapter schema file. ## General fields | Field | Required | Description | | ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `$id` | Yes | The unique ID and name of the schema file. | | `type` | No | The data type of the schema item. Provide this field if you want type validation. | | `schema` | Yes | The JSON schema specification version. The adapter uses Ajv for validation, so this must be a version supported by Ajv. | | `description` | No | A human-readable description of the schema item. | | `translate` | No | **Adapter-specific.** Available on any object-type field. Controls whether the adapter library runs field translation on this schema or object. Defaults to `true` at the schema level and is inherited by child objects. | | `dynamicfields` | No | **Adapter-specific.** Available on any object-type field. When `true`, fields not explicitly defined in the schema are passed through as-is rather than being dropped. Defaults to `false` at the schema level and is inherited by child objects. | | `properties` | Yes | Contains all data field definitions within the schema. | | `ph_request_type` | Yes | **Adapter-specific.** An internal field used by the adapter library to identify the action. Never included in the data sent to the external system. The `enum` must list every action that uses this schema file, and `default` must be set to one of those values. | | `default` | No | The default value for a field. Use with care — defaults can introduce unexpected data in requests and responses. Also apply constraints like `min`/`max` only when they are appropriate for the specific request or response. | | `enum` | No | The allowed values for a string field. For `ph_request_type`, this must include every action that uses the schema. | | Property names | No | TheItential Platform name for the field — howItential Platform will refer to this data. For example, `ip_address` or `username`. | | `external_name` | No | **Adapter-specific.** The field name the external system uses for the same data. When this differs from the property name, the adapter automatically translates the field name in both directions. | ### Example ```json { "$id": "reqTokenSchema.json", "type": "object", "schema": "http://json-schema.org/draft-07/schema#", "translate": true, "dynamicfields": true, "properties": { "ph_request_type": { "type": "string", "description": "type of request (internal to adapter)", "default": "getToken", "enum": ["getToken", "healthcheck"], "external_name": "ph_request_type" }, "username": { "type": "string", "description": "username to log in with", "external_name": "user_name" }, "password": { "type": "string", "description": "password to log in with", "external_name": "passwd" }, "ip_address": { "type": "string", "description": "IAP uses ip_address; System A uses ip_addr", "external_name": "ip_addr" } }, "definitions": {} } ``` ## Security fields | Field | Required | Description | | -------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `parse` | No | **Adapter-specific.** When `true`, the adapter parses this field's value as JSON (useful when a field contains a stringified object). Defaults to `false`. | | `encode` | No | **Adapter-specific.** When `true`, the adapter base64-encodes this field on the request and decodes it on the response. Defaults to `false`. | | `encrypt.type` | No | **Adapter-specific.** The encryption algorithm to use for this field. Currently only `AES` is supported. Omit to disable encryption. | | `encrypt.key` | No | **Adapter-specific.** The key used to encrypt and decrypt the field value. | ### Example ```json { "$id": "reqTokenSchema.json", "properties": { "username": { "type": "string", "description": "username to log in with", "parse": true, "encode": false, "encrypt": { "type": "AES", "key": "sfhgjhajlgsfhjlaghlshdg" }, "external_name": "user_name" } }, "definitions": {} } ``` ## Required fields You can mark fields as required using standard JSON schema techniques. When a required field is missing from the request, the adapter returns a validation error without making a call to the external system — avoiding unnecessary failures and saving time. You can require a field unconditionally using a top-level `required` array, or conditionally using `if`/`then` logic based on the action. ### Conditionally required field This example requires `origin` only when the action is `createAlert`. ```json { "$id": "sevone_alert", "type": "object", "$schema": "http://json-schema.org/draft-07/schema#", "properties": { "ph_request_type": { "type": "string", "default": "getAlerts", "enum": [ "getAlerts", "getAlertsFiltered", "getAlertsForDevice", "getAlertsForMapConnection", "getAlertsForMapNode", "createAlert", "updateAlert", "assignAlert", "ignoreAlert", "clearAlert", "deleteAlert" ], "external_name": "ph_request_type" }, "id": { "type": "integer", "description": "id of the alert", "minimum": 0, "maximum": 999999999999, "external_name": "sys_id" }, "origin": { "type": "string", "description": "where this alert originated", "external_name": "origin" } }, "allOf": [ { "if": { "properties": { "ph_request_type": { "enum": ["createAlert"] } } }, "then": { "required": ["origin"] } } ], "definitions": {} } ``` ### Encode a field value Setting `encode` to `true` on a field causes the adapter to base64-encode that field's value before sending it to the external system, and decode it when receiving the response. If you want to encode on the request but not decode on the response, use separate request and response schemas and only set `encode: true` in the request schema. ```json { "$id": "reqTokenSchema.json", "properties": { "Data": { "type": "object", "properties": { "Data": { "type": "string", "encode": true, "external_name": "Data" } }, "external_name": "Data" } }, "definitions": {} } ``` #### Before and after **Without encoding:** ```json { "Data": { "returnStatus": false, "RecordCount": 0, "Data": "something random" } } ``` **With `encode: true`:** ```json { "Data": { "returnStatus": false, "RecordCount": 0, "Data": "c29tZXRoaW5nIHJhbmRvbQ==" } } ``` ### Encrypt a field value