ConfigureEndpoint configurationSchemas

Schema 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

FieldRequiredDescription
$idYesThe unique ID and name of the schema file.
typeNoThe data type of the schema item. Provide this field if you want type validation.
schemaYesThe JSON schema specification version. The adapter uses Ajv for validation, so this must be a version supported by Ajv.
descriptionNoA human-readable description of the schema item.
translateNoAdapter-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.
dynamicfieldsNoAdapter-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.
propertiesYesContains all data field definitions within the schema.
ph_request_typeYesAdapter-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.
defaultNoThe 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.
enumNoThe allowed values for a string field. For ph_request_type, this must include every action that uses the schema.
Property namesNoTheItential Platform name for the field — howItential Platform will refer to this data. For example, ip_address or username.
external_nameNoAdapter-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

1{
2  "$id": "reqTokenSchema.json",
3  "type": "object",
4  "schema": "http://json-schema.org/draft-07/schema#",
5  "translate": true,
6  "dynamicfields": true,
7  "properties": {
8    "ph_request_type": {
9      "type": "string",
10      "description": "type of request (internal to adapter)",
11      "default": "getToken",
12      "enum": ["getToken", "healthcheck"],
13      "external_name": "ph_request_type"
14    },
15    "username": {
16      "type": "string",
17      "description": "username to log in with",
18      "external_name": "user_name"
19    },
20    "password": {
21      "type": "string",
22      "description": "password to log in with",
23      "external_name": "passwd"
24    },
25    "ip_address": {
26      "type": "string",
27      "description": "IAP uses ip_address; System A uses ip_addr",
28      "external_name": "ip_addr"
29    }
30  },
31  "definitions": {}
32}

Security fields

FieldRequiredDescription
parseNoAdapter-specific. When true, the adapter parses this field’s value as JSON (useful when a field contains a stringified object). Defaults to false.
encodeNoAdapter-specific. When true, the adapter base64-encodes this field on the request and decodes it on the response. Defaults to false.
encrypt.typeNoAdapter-specific. The encryption algorithm to use for this field. Currently only AES is supported. Omit to disable encryption.
encrypt.keyNoAdapter-specific. The key used to encrypt and decrypt the field value.

Example

1{
2  "$id": "reqTokenSchema.json",
3  "properties": {
4    "username": {
5      "type": "string",
6      "description": "username to log in with",
7      "parse": true,
8      "encode": false,
9      "encrypt": {
10        "type": "AES",
11        "key": "sfhgjhajlgsfhjlaghlshdg"
12      },
13      "external_name": "user_name"
14    }
15  },
16  "definitions": {}
17}

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.

1{
2  "$id": "sevone_alert",
3  "type": "object",
4  "$schema": "http://json-schema.org/draft-07/schema#",
5  "properties": {
6    "ph_request_type": {
7      "type": "string",
8      "default": "getAlerts",
9      "enum": [
10        "getAlerts", "getAlertsFiltered", "getAlertsForDevice",
11        "getAlertsForMapConnection", "getAlertsForMapNode",
12        "createAlert", "updateAlert", "assignAlert", "ignoreAlert",
13        "clearAlert", "deleteAlert"
14      ],
15      "external_name": "ph_request_type"
16    },
17    "id": {
18      "type": "integer",
19      "description": "id of the alert",
20      "minimum": 0,
21      "maximum": 999999999999,
22      "external_name": "sys_id"
23    },
24    "origin": {
25      "type": "string",
26      "description": "where this alert originated",
27      "external_name": "origin"
28    }
29  },
30  "allOf": [
31    {
32      "if": { "properties": { "ph_request_type": { "enum": ["createAlert"] } } },
33      "then": { "required": ["origin"] }
34    }
35  ],
36  "definitions": {}
37}

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.

1{
2  "$id": "reqTokenSchema.json",
3  "properties": {
4    "Data": {
5      "type": "object",
6      "properties": {
7        "Data": {
8          "type": "string",
9          "encode": true,
10          "external_name": "Data"
11        }
12      },
13      "external_name": "Data"
14    }
15  },
16  "definitions": {}
17}

Before and after

Without encoding:

1{
2  "Data": {
3    "returnStatus": false,
4    "RecordCount": 0,
5    "Data": "something random"
6  }
7}

With encode: true:

1{
2  "Data": {
3    "returnStatus": false,
4    "RecordCount": 0,
5    "Data": "c29tZXRoaW5nIHJhbmRvbQ=="
6  }
7}

Encrypt a field value