Configuring JSON attribute constraints
The PingDirectory server can define several constraints for the fields included in JSON objects stored in values of a specified attribute type.
Defining constraints on JSON object fields allows administrators to set requirements on what values a JSON field can take to ensure consistency across entries.
Constraints that can be placed on a JSON field include:
-
Requiring values of the field to have a specified data type.
-
Indicating whether the field is required or optional.
-
Indicating whether the field can have multiple values in an array. If a field is permitted to have array values, restrictions can also be placed on the number of elements that can be present in the array.
-
Indicating whether the field can have a value that is the null primitive as an alternative to values of the indicated data type.
-
Restricting values of string fields to a predefined set of values that match a given regular expression or to a length specified by the user.
-
Restricting values of numeric fields with upper and lower bounds.
Only new entries are subject to the new constraints. Existing data that doesn’t match newly-defined JSON constraints can still be decoded and managed by the server. Attempts to alter existing entries with non-compliant JSON objects might require fixing those objects to conform to the new constraints. |
The global configuration properties that define schema constraints for JSON objects are create-json-attribute-constraints
and create-json-field-constraints
in dsconfig
. In dsconfig
interactive, under advanced settings, the menu options are JSON Attribute Constraints
and JSON Field
Constraints
.
Configuration properties for each include:
attribute-type
-
The name or object identifier of the attribute type with which the definition is associated. This attribute type must have the JSON object syntax.
attribute-type
is the naming attribute for the configuration entry. allow-unnamed-fields
-
A Boolean value that indicates whether JSON objects, used as the values of attributes of the associated type, can include fields that are not referenced in the
attribute-value-constraints
object. The default value istrue
.
If allow-unnamed-fields
is true
JSON objects can have fields that are not referenced, and no constraints are imposed on those fields. If allow-unnamed-fields
isfalse
, JSON objects can only have the defined fields.
Unless a schema definition is configured with |
As with the standard LDAP schema, JSON schema constraints are enforced for any changes made after the constraints are defined. If there are already JSON values in the data before a JSON schema is defined for that attribute type, or before changes are made, values that already exist might violate those constraints. JSON schema constraints are also enforced for data provided in an LDIF import, and entries containing JSON objects that violate these constraints are rejected.
Property | Description |
---|---|
|
Specifies the path to the target field as a string with periods to separate levels of hierarchy. If any field name in the hierarchy includes a period, then that period must be escaped with a backslash. |
|
Specifies the expected data type for the target field. The available values are:
|
|
Specifies whether the target field is required to be present. If the target field is present, its value must be either |
|
Indicates whether the target field can be an array. If the value can be an array, all of the elements of the array must be of the type specified in the Values are:
|
|
Specifies whether the target field can have a value of If the field constraint is present, |
|
Specifies whether empty objects are permitted if the value of the target field is a JSON object or an array of JSON objects. If the field constraint is present, the value must be either |
|
Specifies whether values of the target field should be indexed in backends. If the field constraint is present, the value must be either |
|
Specifies the maximum number of entries in which a particular value can appear before the entry ID list for that value is no longer maintained. If the field constraint is present, the value must be an integer greater than or equal to 1. If the constraint is absent, the server uses the default index entry limit for the associated backend. This is only applicable if |
|
Specifies whether backends should prime the contents of the JSON index database into memory when they are opened. This is ignored if the backend’s |
|
Specifies the cache mode to use for the contents of the JSON index database. If the value is not specified, the backend’s default cache mode is used. If a cache mode of |
|
Specifies whether values of the target field should be tokenized in backends. If the field constraint is present, the value is either |
|
Specifies an explicit set of values allowed in the target field . If the field constraint is present, the value must be an array of strings. Any attempt to use a value not in this array for the associated field is rejected. |
|
Specifies a regular expression that the target field must match If the field constraint is present, the value must be a single string or an array of strings representing valid regular expressions (which might require escaping to represent in JSON). Any attempt to use a value that does not match one of the provided regular expressions is rejected. |
|
Specifies the lower bound for values of the target field If the field constraint is present, the value must be a single number and can be an integer. Any attempt to use a value that is less than this number is rejected. |
|
Specifies the upper bound for values of the target field If the field constraint is present, the value must be a single number and can be an integer. Any attempt to use a value that is greater than this number is rejected. |
|
Specifies the minimum number of characters allowed for values of the target field If the field constraint is present, the value must be an integer. Any attempt to use a value with fewer characters than this number is rejected. |
|
Specifies the maximum number of characters allowed for values of the target field If the field constraint is present, the value must be an integer. Any attempt to use a value with more characters than this number is rejected. |
|
Specifies the minimum number of elements that must be present in an array If the field constraint is present, the value must be an integer. Any attempt to use an array with fewer elements is rejected. |
|
Specifies the maximum number of elements that must be present in an array If the field constraint is present, the value must be an integer. Any attempt to use an array with more elements is rejected. |
When writing JSON objects in a local database backend, field names and JSON primitive values of null
, true
, and false
are always tokenized. Integers are either tokenized or compacted using their two’s complement representation. Other numbers are stored using string representations. Array and object sizes are compacted, and their contents are compacted based on their data types.
String values are tokenized and match a recognizable format, including:
-
Dates and times in common generalized time and ISO 8601 formats
-
UUIDs in which the alphabetic characters are either all uppercase or all lowercase
-
Strings of at least 12 bytes that are a valid base64 encoding
-
Strings of at least 6 bytes that are a valid hexadecimal encoding, in which the alphabetic characters are either all uppercase or all lowercase
Adding constraints to JSON attributes
About this task
To create and configure JSON attribute constraints:
Steps
-
Run
dsconfig
with thecreate-json-attribute-constraints
option.Example:
In this example, a JSON attribute constraint is defined on the
appjson
attribute type. This constrains values of theappjson
attribute to be JSON objects. Becauseallow-unnamed-fields
is set to false, those JSON objects can only have fields for which there is a corresponding JSON field constraints definition.appjson
is meant to be replaced by the name of the user’s desired attribute type, as defined in the directory schema. For more information, see About managing JSON attribute values.$ bin/dsconfig create-json-attribute-constraints \ --attribute-type appjson \ --set enabled:true \ --set allow-unnamed-fields:false
Example:
In this example, a JSON field constraint object is defined for the
email.verified
field. Theemail.verified
field must be present and must take a boolean value.$ bin/dsconfig create-json-field-constraints \ --attribute-type appjson \ --json-field email.verified \ --set value-type:boolean \ --set is-required:true \ --set index-values:false \ --set tokenize-values:false \ --set allow-null-value:true
Example:
In this example, a JSON field constraint object is defined for the
email.type
field. Theemail.type
field must be present and must take a value ofhome
,work
, orother
.$ bin/dsconfig create-json-field-constraints \ --attribute-type appjson \ --json-field email.type \ --set value-type:string \ --set is-required:true \ --set index-values:false \ --set tokenize-values:true \ --set allowed-value:home \ --set allowed-value:other \ --set allowed-value:work \ --set allow-null-value:false
Example:
In this example, a JSON field constraint is defined for the
email.value
field. Theemail.value
field must be present and must take a string value that matches the specified regular expression.$ bin/dsconfig create-json-field-constraints \ --attribute-type appjson \ --json-field email.value \ --set value-type:string \ --set is-required:true \ --set index-values:true \ --set tokenize-values:false \ --set prime-index:true \ --set allow-null-value:true \ --set maximum-value-length:256 \ --set minimum-value-length:1 \ --set allowed-value-regular-expression:[-_\+\.\w\d]+@\w+\.\w{2,5}