Schema Field Definitions
  • 21 Nov 2022
  • Dark
    Light
  • PDF

Schema Field Definitions

  • Dark
    Light
  • PDF

Article summary

Schema files are based on a JSON schema with added fields utilized by the adapter libraries. So, if it works in the JSON schema, it should work in the schema file.

General Field Definitions

The following tables defines general field definitions used in schema files.

Field Required Definition
$id Yes This is the id/name of the schema and should be unique.
type No Used in several places, it is the data type associated with a specific schema item. If you want type validation, then this field should be provided.
schema Yes This is the JSON schema specification used by the adapter’s schema file. The adapter uses Ajv to check the data against the schema so this specification should be one that is supported by Ajv.
description No Used in many places, it is the description associated with a specific schema item.
translate No This field is an adapter specific field. It is available on any object type field. It tells the adapter library whether to run translation (or not) on the schema or object. Adapters will often be generated with an empty schema file and translation set to false as that is a simpler schema file. It defaults to true on the schema and is inherited from parents on objects within the schema.
dynamicfields No This field is an adapter specific field. It is available on any object type field. It tells the adapter library whether to include any undefined fields in the data that it returns from the translator. It defaults to false on the schema and is inherited from parents on objects within the schema.
properties Yes This field contains all the data fields within the schema.
ph_request_type Yes This field is an adapter specific field. This property should be set in every adapter schema file. It is never included with the data but used internally by the adapter library. It should have an enum that includes every action that uses this schema file. The default is required here and should be set to one of those actions.
default No Defines the default value for the data field. In the case of ph_request_type it must be one of the values in the enum. In general, be careful using default as it is possible to get data that you do not want inside your request/response. It is also best to be careful when using certain data rules (e.g., min/max). Make sure they are appropriate for the request/response.
enum No Defines the values that a data field of type string can have. In the case of ph_request_type, it is important that enum include every action that uses this schema.
Property names No These refer to how the data should be presented to IAP. In the earlier example, IAP referred to IP addresses as ip_address. Accordingly, that means the value in this field would be ip_address. In the case of token requests, in most cases, there should be a username property and a password property.
external_name No This field is added by the adapter. It is how the data should be presented to the system we are integrating with. In the prior example, System A referred to IP address as ip_addr. So for this field, the value would be set to ip_addr.

Example: General Field Definitions

  "$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 wants ip_address, System A wants ip_addr",
      "external_name": "ip_addr"
    }
  },
  "definitions": {}

Security Field Definitions

Field Required Definition
parse No This field is an adapter specific field. It tells the adapter if this field needs to be independently parsed (maybe it was stringified within the object that was sent). The default is false.
encode No This field is an adapter specific field. It tells the adapter whether to endode/decode the data contained within this field. Encoding is base 64. The default is false.
encrypt.type No This field is an adapter specific field. It tells the adapter whether to encrypt/decrypt the data contained within this individual field. The default is no type.

Different encryption types are supported in the type field, but at the current time only AES encryption is used.
encrypt.key No This contains the key used to encrypt/decrypt the data in the field. The default is no key.

Example: Security Field Definitions

  "$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": {}

Making Data Required

You can have required fields within the schema using standard JSON schema techniques like having a list of “required” properties using a required value. You can also use more complex techniques for “required” properties based on the action.

One advantage of using required properties is that invalid requests will not be sent to the other system, thereby causing the system to error. Instead, the error will be returned by the adapter. This technique is not only efficient but saves time!

Example: Making Data Required

  "$id": "sevone_alert",
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "ph_request_type": {
      "type": "string",
      "description": "type of request (internal to adapter)",
      "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 in sevone",
      "minimum": 0,
      "maximum": 999999999999,
      "external_name": “sys_id"
    },
    "origin": {
      "type": "string",
      "description": "where this alert was originated from",
      "external_name": "origin"
    }
  },
  "allOf": [
    {
      "if" : { "properties" : { "ph_request_type": { "enum": ["createAlert"] } } },
      "then" : { "required" : ["origin"] }
    }
  ],
  "definitions": {}

Was this article helpful?

Changing your password will log you out immediately. Use the new password to log back in.
First name must have atleast 2 characters. Numbers and special characters are not allowed.
Last name must have atleast 1 characters. Numbers and special characters are not allowed.
Enter a valid email
Enter a valid password
Your profile has been successfully updated.