When it comes to creating filters for your Webhook subscriptions, the Identity Cloud uses a subset of the JSON Schema draft 7 validation language. The keywords that can be included in an Identity Cloud filter are summarized in the following tables.
General Validation
Keyword | Description |
const | To validate, a value must exactly match the const value. For example, suppose you use the captureApplicationId property and set the const keyword to xj2dmg2mqsm6a8gx89cwn3fu929p4pd. In that case, only events where the captureApplicationId is equal to xj2dmg2mqsm6a8gx89cwn3fu929p4pd pass validation. Note that, when using const, matches must be exact: validation fails if you try to use a wildcard value such as xj2dmg2*. |
enum | Validation requires a value to be equal to at least one of the items in the enum array. For example, suppose you have the following schema: { "enum": ["red", "orange", "yellow", "green", "blue", "indigo", "violet"] } In that case:
|
additionalProperties | When set to false, indicates that all unfiltered events are automatically ignored. See this article for more information. |
Numeric and String Validation
Keyword | Description |
exclusiveMaximum | Specifies the maximum value for a number, not including the specified maximum itself (i.e., validation requires a value to be less than the specified maximum). For example, suppose you set exclusiveMaximum to 7. In that case:
|
exclusiveMinimum | Specifies the minimum value for a number, not including the specified minimum itself (i.e., validation requires a value to be greater than the specified minimum). For example, suppose you set exclusiveMinimum to 10. In that case:
|
format | Enables more-specific validation of string values. The following format types are supported:
|
maximum | Validation requires a number to be less than or equal to the maximum. For example, suppose you set the maximum for a numeric value to 603. In that case:
|
maxLength | Maximum number of characters that a string can possess in order to pass validation: the value must have a “length” less than or equal to the maxLength. For example, suppose you set maxLength to 10. In that case:
|
minimum | Validation requires a number to be greater than or equal to the minimum. For example, suppose you set the minimum for a numeric value to 603. In that case:
|
minLength | Minimum number of characters that must be in a string for that value to pass validation: the value must have a “length” greater than or equal to the minLength. For example, if minLength is set to 7 then: The string value “seventeen” passes validation because it has at least 7 characters.
|
multipleOf | To pass validation, a number must be evenly divisible by the multipleOf value (i.e., there is no remainder). For example, suppose you set multipleOf to 4. In that case:
|
pattern | Validates a string against a regular expression. Regular expressions are composed using the ECMA 262 regular expression dialect. For example, suppose you use the following regular expression, in which validation occurs only if the value begins with the lowercase letters a, b, or c: ^[abc] In that case:
|
Annotations and Comments
Keyword | Description |
$comment | Descriptive information typically aimed developers. You can intersperse multiple comments throughout a filter. |
default | Specifies the value that should be used if no other value was supplied; for example, US might be the default value for a country attribute. Note, however, that default is used only to help explain the schema and how it works: if no value is supplied the default value is not substituted nor is the default value used in validation. For example, the following schema sets US as the default for the country attribute: "country": { "default": "US" ] } However, if a user fails to enter a value for the country attribute then the country attribute will remain as-is: the null value will not be replaced by the default value. |
description | String value that explains the schema and what it’s used for. The description is ignored when the schema is validated. For example: { "description": "This schema validates the Capture client ID." } |
examples | Sample values that, if used, would validate. These values are provided to help explain how the schema works, and aren’t actually used in validation. For example: "examples": [ "karim.nafir@mail.com", "augustjosephspringer@gmail.com" ] |
title | Brief title applied to the schema. For example: { "title": "entityCreated Validation" } |
Arrays and Array Validation
Keyword | Description |
contains | Validation requires a value to match at least one of the items in the contains array. For example, suppose we have the following schema, which specifies that the array being validated must contain a numeric value: { "type": "array", "contains": { "type": "number" } } In that case:
|
items | Validation requires each item in an array to meet the specified schema. For example, suppose we have the following schema, which specifies that all the items in an array be numbers: { "type": "array", "items": { "type": "number" } } In that case:
|
maxContains | Validation requires that the value match no more items in an array that the number specified by maxContains. For example, suppose maxContains is set to 2 using the following array: ["A", "B", "C", "D", "E", "F", "G"] In that case:
|
maxItems | An array must contain no more than the number of items specified by the maxItems value. For example, suppose you set the maxItems for an array to 3. In that case:
|
minContains | Validation requires that the value match, at the very least, the number of items in an array specified by minContains. For example, suppose minContains is set to 2 using the following array: ["A", "B", "C", "D", "E", "F", "G"] In that case:
Note that this value can be set to 0. However, unless the maxContains validation is included, anything set to minContains = 0 will always pass validation. |
minItems | An array must contain at least the minimum number of items specified by the minItems value. For example, suppose minItems is set to 3. In that case:
|
uniqueItems | Specifies that all the items in an array must be unique. For example, suppose you set uniqueItems to true. In that case:
If uniqueItems is set to false (or is omitted), then it doesn’t matter whether or not the items in an array are unique. |
Schemas and Schema Validation
Keyword | Description |
$schema | Defines the JSON “dialect” used in creating (and required for interpreting) the schema. Currently Webhooks only accepts the http://json-schema.org/draft-07/schema schema: "$schema": "http://json-schema.org/draft-07/schema", |
allOf | A value must validate against all the items in a sub-schema. For example, the following schema specifies a number that has a minimum value of 5 and a maximum value of 10: { "allOf": [ { "type": "number", "minimum": 5 }, { "type": "number", "maximum": 10 } ] } In this case:
|
anyOf | A value must validate against at least one of the items in a sub-schema. For example, the following schema specifies a value that is either a string or a number: { "anyOf": [ { "type": "string" }, { "type": "number" } ] } In this case;
|
oneOf | A value must validate against one, but only one, of the items in a sub-schema. For example, suppose you have the following schema: { "oneOf": [ { "type": "number", "multipleOf": 6 }, { "type": "number", "multipleOf": 4 } ] } In that case:
|
Data Type Validation
Keyword | Description |
type | Specifies the datatype of a value. Allowed datatypes are:
|
Objects and Object Validation
Keyword | Description |
dependentRequired | If the object includes a specified property then it must also include one or more related properties in order to validate. For example, if an object includes a creditCard property you might also require a phoneNumberand homeAddress property. In that case, phoneNumber and homeAddress are dependent properties. For example: { "type": "object", "properties": { "name": { "type": "string" }, "creditCard": { "type": "number" }, "phoneNumber": { "type": "string" } "homeAddress": { "type": "string" } }, "required": ["name"], "dependentRequired": { "creditCard": ["phoneNumber", "homeAddress"] } } In the dependentRequired portion of the schema, creditCard is the target property, and phoneNumber and homeAddress are the other two properties that must be present along with creditCard. If any of these properties are missing, the objects fails validation. |
maxProperties | When working with an object, that object can contain no more properties than the number specified by the maxProperties value. For example, suppose you set the maxProperties for an object to 2. In that case:
|
minProperties | When working with an object, that object must contain at least the number of properties specified by the minProperties value. For example, suppose you set the maxProperties for an object to 3. In that case:
|
patternProperties | Enables you to use regular expressions to define an object schema. For example, consider the following (and extremely simple schema): { type: "object", patternProperties: { "Name$": {type: "string"} } } When using patternProperties, the key ($Name) is a regular expression used on property names. The regular expression $Namechecks for property names that end in name (for example, firstName). Meanwhile, the value (type: “string”) are the validation requirements. With his simple schema, an object can’t pass validation unless all properties with a name ending in name are string properties. For example:
|
properties | Defines the properties of an object. If any of the defined properties are used in the object being validated, they must meet the property definitions (for example, a given property must be a string value rather than a Boolean value). However, the object doesn’t have to include all the defined properties, and can even include properties that haven’t been defined. For example, suppose have the following schema, which defines an object with 2 properties (id and name): { "type": "object", "properties": { "id": { "type": "number" }, "name": { "type": "string" } } } In this case:
|
propertyNames | Enables you to validate property names in an object against a specified schema (and by using regular expressions). For example, suppose you require all property names to begin with the string value akamai. In that case, you could use a validation schema similar to this: { "type": "object", "propertyNames": { "pattern": "^akamai" } } With the preceding, a property name like akamaiId passes validation; a property name like customerId would not pass validation. |
required | Validation requires an object to include all the properties specified in the required array. For example, this schema requires the object includes the captureClientId and entityType properties: "required": [ "captureClientId", "entityType" ] |
Conditional Actions
Keyword | Description |
if - then - else | if – then - else Enables you to apply different validation criteria depending on the values assigned to specified properties. For example, consider this schema: "if": { "properties": { "captureApplicationId": { "const": "htb8fuhxnf8e38jrzub3c7pfrr" } } }, "then": { "properties": { "captureClientId": { "const": " xj2dmg2mqsm6a8gx89cwn3fu929p4pd"} }, "else": { "properties": { "captureClientId": { "const": " 3bchk5hsx6v58dkn288nbybmxfyk32u7"} } In the preceding schema, we use this syntax to cee if the Capture application ID reported in a Webhook notification is equal to htb8fuhxnf8e38jrzub3c7pfrr: "if": { "properties": { "captureApplicationId": { "const": "htb8fuhxnf8e38jrzub3c7pfrr" } } }, If this is true, if the notification involves the specified Capture application, we then use this section to verify that the client ID isxj2dmg2mqsm6a8gx89cwn3fu929p4pd: "then": { "properties": { "captureClientId": { "const": " xj2dmg2mqsm6a8gx89cwn3fu929p4pd"} }, If the client ID isxj2dmg2mqsm6a8gx89cwn3fu929p4pd then the notification passes validation. And what if the Capture application ID isn’thtb8fuhxnf8e38jrzub3c7pfrr? In that case, we check to see if the client ID is 3bchk5hsx6v58dkn288nbybmxfyk32u7: "else": { "properties": { "captureClientId": { "const": " 3bchk5hsx6v58dkn288nbybmxfyk32u7"} } If true, then the notification passes validation. Admittedly, that all sounds a bit confusing, to say the least. In a nutshell, however, here’s what our if – then – else statement is doing:
|
Bonus: Using Annotations and Comments in a Filter
For simple filters (e.g., a filter that only forwards entityUpdated events associated with a specified application) you might not need any descriptive elements: the filter will likely be self-explanatory as it is. As you start to create more-complex filters, however, that might not always be true: in cases like that, it might be useful to include a filter description or an occasional comment. In the following filter we added the title, description, and $comment keywords, just to give you an example of how you can annotate filters:
"filter": {
"$schema": "http://json-schema.org/draft-07/schema",
"title": "Application ID Filter",
"description": "This filter limits forwarded data to those events that include one of the two captureApplicationIds referenced by the enum keyword."
"propertjes": {
"entityUpdated": {
"properties": {
"captureApplicationId": {
"enum": ["zzyn9gy9r8xdy5zkru4y54syk6", "htb8fuhxnf8e38jrzub3c7pfrr"],
"$comment": "You can find application IDs by going to the Manage Application page in Console."
}
}
}
}
}