Schema Field Definitions

Updated on 21 Nov 2022

Dark

Light
PDF

Article summary

Did you find this summary helpful?

Thank you for your feedback

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?

What's Next

Introduction - Schema Usage & Examples

Table of contents