> 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 usage examples

> Examples covering how schemas are referenced in action.json, including file organization and using separate request and response schemas.

## Referencing schemas in action.json

Every action must reference at least one schema. You can use a shared `schema` field for both request and response, or define `requestSchema` and `responseSchema` separately.

* `schema` — Used when the request and response share the same schema, or as a fallback when no specific schemas are defined.
* `requestSchema` — A schema specific to the request.
* `responseSchema` — A schema specific to the response.

```json
{
  "name": "getIP",
  "protocol": "REST",
  "method": "GET",
  "entitypath": "{base_path}/{version}/addresses/{pathv1}",
  "schema": "schema.json",
  "requestSchema": "requestSchema.json",
  "responseSchema": "responseSchema.json",
  "timeout": 3000,
  "sendEmpty": true,
  "datatype": "PLAIN",
  "headers": {},
  "responseObjects": [
    {
      "type": "default",
      "key": "",
      "mockFile": ""
    }
  ]
}
```

### Organizing schema files in subdirectories

You can move schema files into a subdirectory within the entity folder. Update the paths in `action.json` to match.

```json
{
  "requestSchema": "schemas/requestSchema.json",
  "responseSchema": "schemas/responseSchema.json"
}
```

## No translation

Adapter Builder often generates a simple schema with translation disabled. This is easier to understand and requires less configuration. With `translate` set to `false`, all data from the external system is passed toItential Platform unchanged, and all data fromItential Platform is sent to the external system unchanged — no field name mapping occurs.

```json
{
  "$id": "deviceSchema.json",
  "type": "object",
  "schema": "http://json-schema.org/draft-07/schema#",
  "translate": false,
  "dynamicfields": true,
  "properties": {
    "ph_request_type": {
      "type": "string",
      "description": "type of request (internal to adapter)",
      "default": "getDevice",
      "enum": ["getDevice", "createDevice"],
      "external_name": "ph_request_type"
    }
  },
  "definitions": {}
}
```

## Token schemas

Token requests are a common case where separate request and response schemas are useful. The request typically requires specific fields (such as `username` and `password`) that do not appear in the response. Using separate schemas lets you enforce required fields on the request without affecting response validation.

This example translates `username` → `user_name` and `password` → `passwd` on the request, and maps `access_token` → `token` on the response.

Because the response schema does not set `dynamicfields`, it defaults to `false`. This means only the fields explicitly defined in the response schema — in this case, `token` — are returned toItential Platform. All other fields in the response are dropped.

### Request token schema

```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"
    }
  },
  "required": ["username", "password"],
  "definitions": {}
}
```

### Response token schema

```json
{
  "$id": "respTokenSchema.json",
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "translate": true,
  "properties": {
    "ph_request_type": {
      "type": "string",
      "description": "type of request (internal to adapter)",
      "default": "getToken",
      "enum": ["getToken"],
      "external_name": "ph_request_type"
    },
    "token": {
      "type": "string",
      "description": "the token returned from the system",
      "external_name": "access_token"
    }
  },
  "definitions": {}
}
```

## Dynamic fields and translation

You can define a schema that translates specific fields while passing all other fields through as-is. This is useful when you want to validate or rename certain fields but do not want to enumerate the full data structure.

Setting `dynamicfields` to `true` tells the adapter library to include any field not explicitly defined in the schema and return it unchanged. When `external_name` differs from the property name, the adapter translates that field in both directions — Itential Platform receives the property name, and the external system receives the `external_name`.

In the example below:

* `componentId` inItential Platform maps to `objectId` in the external system.
* `deviceId` uses the same name in both systems.
* Any other fields in the data are passed through without modification.

```json
{
  "$id": "sevone_alert",
  "type": "object",
  "schema": "http://json-schema.org/draft-07/schema#",
  "translate": true,
  "dynamicfields": true,
  "properties": {
    "ph_request_type": {
      "external_name": "ph_request_type"
    },
    "deviceId": {
      "type": "integer",
      "description": "the id of the device this alert originated on",
      "external_name": "deviceId"
    },
    "componentId": {
      "type": "integer",
      "description": "the id of the component this alert originated on",
      "external_name": "objectId"
    }
  },
  "definitions": {}
}
```

## Conditionally required fields

Calls to external systems can be costly. When required information is missing, it is more efficient for the adapter to return a validation error immediately rather than forwarding an incomplete request to the external system.

The adapter runs Ajv validation against the schema before making a call. If validation fails, the adapter returns an error without contacting the external system.

### Require a field on a specific action

Use `if`/`then` with `allOf` to make a field required only for certain actions. This example requires `origin` only when `ph_request_type` 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": {}
}
```

### Require one of several fields

You can also require at least one field from a set using `oneOf`. This example requires either `componentId` or `deviceId` for `createAlert`. If both are missing, Ajv validation fails and the adapter returns an error without making the request.

```json
{
  "$id": "sevone_alert",
  "properties": {
    "ph_request_type": {
      "enum": ["createAlert"],
      "external_name": "ph_request_type"
    },
    "deviceId": {
      "type": "integer",
      "description": "the id of the device this alert originated on",
      "external_name": "deviceId"
    },
    "componentId": {
      "type": "integer",
      "description": "the id of the component this alert originated on",
      "external_name": "objectId"
    }
  },
  "allOf": [
    {
      "if": { "properties": { "ph_request_type": { "enum": ["createAlert"] } } },
      "then": {
        "oneOf": [
          { "required": ["deviceId"] },
          { "required": ["componentId"] }
        ]
      }
    }
  ],
  "definitions": {}
}
```

## Parse field value

Some external systems return data where a field contains a stringified JSON value — a JSON object or array that has been serialized into a string. Setting `parse` to `true` on a field tells the adapter to parse that string back into structured JSON before returning it toItential Platform.

```json
{
  "$id": "reqTokenSchema.json",
  "properties": {
    "Data": {
      "type": "object",
      "properties": {
        "Data": {
          "type": "string",
          "parse": true,
          "external_name": "Data"
        }
      },
      "external_name": "Data"
    }
  },
  "definitions": {}
}
```

### Before and after

**Without `parse`**, the inner `Data` field is returned as a raw string:

```json
{
  "ResponseType": "SUCCESS",
  "Data": {
    "Message": "",
    "MessageType": "Success",
    "returnStatus": false,
    "RecordCount": 0,
    "Data": "[{\"siteid\":\"XXXXX\",\"ng_rtr_pair_nm\":\"XXXXXXX\",\"ngmadrtr_id1\":\"XXXXXX\",\"ngmadrtr_id2\":\"XXXXXX\",\"ng_rtr_port\":\"2/1/5\",\"eth_term_mso\":\"XXXXX\"}]"
  }
}
```

**With `parse: true`**, the adapter parses the string and returns structured JSON:

```json
{
  "ResponseType": "SUCCESS",
  "Data": {
    "Message": "",
    "MessageType": "Success",
    "returnStatus": false,
    "RecordCount": 0,
    "Data": [
      {
        "siteid": "XXXXX",
        "ng_rtr_pair_nm": "XXXXXXX",
        "ngmadrtr_id1": "XXXXXX",
        "ngmadrtr_id2": "XXXXXX",
        "ng_rtr_port": "2/1/5",
        "eth_term_mso": "XXXXX"
      }
    ]
  }
}
```

## Encrypt a field value

Adding an `encrypt` object to a field causes the adapter to encrypt that field's value before sending it to the external system, and decrypt it when receiving the response.

Currently only AES encryption is supported. You must provide both the encryption `type` and the `key` used to encrypt and decrypt.

If you want to encrypt on the request but not decrypt on the response, use separate request and response schemas and only include the `encrypt` object in the request schema.

```json
{
  "$id": "reqTokenSchema.json",
  "properties": {
    "Data": {
      "type": "object",
      "properties": {
        "Data": {
          "type": "string",
          "encrypt": {
            "type": "AES",
            "key": "thisismykey"
          },
          "external_name": "Data"
        }
      },
      "external_name": "Data"
    }
  },
  "definitions": {}
}
```

### Before and after

**Without encryption:**

```json
{
  "Data": {
    "returnStatus": false,
    "RecordCount": 0,
    "Data": "something random"
  }
}
```

**With encryption:**

```json
{
  "Data": {
    "returnStatus": false,
    "RecordCount": 0,
    "Data": "IcNev7McG3/8MOt8QaULRzkNjDdzUKwhf6vEqPZkhog="
  }
}
```