Schema Sometimes Required

Sometimes sending requests to other systems can be costly. As a result, when we know that certain information is required and we do not have that information, it makes sense to error the request before it is sent.

Schema allows us to do this by setting the information that is required on certain actions.

The adapter will run Ajv validation on the data based on the schema. If the origin is not provided, the adapter will return an error without ever making the request to the other system.

This example requires origin to be provided on createAlert.

Example: Schema with Required Field

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

You can also set the schema to say that “one of X” fields are required (as shown in the example below).

In this example, either the componentId or the deviceId are required to create the alert.

If they are both missing, then Ajv validation will result in an error which the adapter libraries will return without making the request to the other system.

Example: Schema with One of the Required Fields

  "$id": "sevone_alert",
  ….
  "properties": {
    "ph_request_type": {
       ….
      "enum": [
        "createAlert”
      ],
      "external_name": "ph_request_type"
    },
    "id": {
      …..
    },
    "deviceId": {
      "type": "integer",
      "description": "the id of the device this alert originated on",
      "external_name": "deviceId"
    },
    "componentId": {
      "type": "integer",
      "description": "the id of the object/device componenet this alert originated on",
      "external_name": "objectId"
    }
  },
  "allOf": [
    {
      "if": { "properties": { "ph_request_type": { "enum": ["createAlert"] } } },
      "then": {
        "oneOf": [
          {
            "required": ["deviceId"]
          },
          {
            "required": ["componentId"]
          }      
        ]
      }
    }
  ],
  "definitions": {}