Configuring JSON attribute constraints

Page created: 15 Jul 2022 |

Page updated: 21 Dec 2022

| 10 min read

Product Directory Capability Product documentation Content Type Administration User task IT Administrator Administrator Audience Software Deployment Method Configuration

server can define a number of constraints for the fields included in JSON objects stored in values of a specified attribute type.

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 specified length
Restricting values of numeric fields with upper and lower bounds

Any existing data that doesn't match newly-defined JSON constraints can still be decoded and managed by the server. Only new entries are subject to the new constraints. Attempts to alter existing entries with non-compliant JSON objects might require fixing those objects to make them conform to the new constraints.

The two 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. This property 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.
If this is false, JSON objects are only permitted to have the defined fields. If this is true, which is the default behavior, JSON objects are permitted to have fields that are not referenced, and no constraints are imposed on those fields.

Unless a schema definition is configured with allow-unnamed-fields set to false, it's only necessary to include information about fields whose values should be indexed or tokenized. However, you might want to define other fields that are expected in order to ensure that clients are not permitted to store invalid values.

As with 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 so that entries containing JSON objects that violate these constraints are rejected.

Property	Description
`field`	Specifies the path to the target field as a string with periods to separate levels of hierarchy If any field name in the hierarchy itself includes a period, that period should be escaped with a backslash.
`value-type`	Specifies the expected data type for the target field Values can include: `any` The target field can have any value. `boolean` The target field must have a value of true or false. `integer` The target field must have a number that can be exactly represented as an integer. `null` The target field must have a value of null. `number` The target field must have a value that represents a valid JSON number `object` The target field must have a value that represents a valid JSON object. The `allowed-fields` array can contain additional elements that define constraints for the fields that might be present in the object. `string` The target field must have a value that represents a valid JSON string.
`is-required`	Specifies whether the target field is required to be present If it is present, its value must be either `true` or `false`. If it is absent, a default of `false` is assumed.
`is-array`	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 `value-type` field. It can be present with a value that is one of the single strings listed below. If it is absent, a value of `prohibited` is assumed. Values include: `required` The target field must be an array with zero or more values of the specified type and must not be a single value of the specified type. `optional` The target field can be an array with zero or more values of the specified type, or it can be a single value of the specified type. `prohibited` The target field must not be an array and can only be a single value of the specified type.
`allow-null-value`	Specifies whether the target field can have a value of `null` as an alternative to the specified `value-type` If present, its value must be either `true` or `false`. If it is absent, a default of `false` is assumed. This has no effect if the value-type is `null`.
`allow-empty-object`	If the value of the target field is a JSON object, or an array of JSON objects, specifies whether empty objects are permitted If present, the value must be either `true`, where the object may have zero or more fields, or `false`, where the object may have one or more fields. If it is absent, a default of `false` is assumed.
`index-values`	Specifies whether values of the target field should be indexed in backends If present, the value must be either `true` (the field should be indexed) or `false` (the field should not be indexed). If it is absent, a default of `false` is assumed. If `true`, the `value-type` must be `boolean`, `integer`, `null`, or `string`.
`index-entry-limit`	Specifies the maximum number of entries in which a particular value may appear before the entry ID list for that value is no longer maintained If present, the value must be an integer greater than or equal to one. If it is absent, the server uses the default index entry limit for the associated backend. This is only applicable if `index-values` is `true`.
`prime-index`	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 `prime-all-indexes` property has a value of `true`.
`cache-mode`	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 `cache-keys-only` is configured, priming only loads the internal nodes into memory for the index. If `no-caching` is configured, no priming is performed for the index.
`tokenize-values`	Specifies whether values of the target field should be tokenized in backends If present, the value is either `true` (field values should be tokenized) or `false`. If it is absent, a value of `false` is assumed. If `true`, the `value-type` must be `string`.
`allowed-values`	Specifies an explicit set of values that the target field is permitted to have If 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. This can only be used with a `value-type` of `string`. If not present, any value can be used as long as it satisfies all other defined constraints.
`allowed-value-regular-expression`	Specifies a regular expression that the target field is required to match If present, the value must be a single string or an array of strings representing valid regular expressions (which may require escaping to represent in JSON). Any attempt to use a value that does not match one of the provided regular expressions is rejected. This can only be used with a `value-type` of `string`. If not present, values are not required to match any regular expression.
`minimum-numeric-value`	Specifies the lower bound for values of the target field If 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. This can only be used with a `value-type` of `integer` or `number`. If not present, no minimum numeric value applies.
`maximum-numeric-value`	Specifies the upper bound for values of the target field If present, the value must be a single number and can be an integer. Any attempt to use a value that is more than this number is rejected. This can only be used with a `value-type` of `integer` or `number`. If not present, no maximum numeric value applies.
`minimum-value-length`	Specifies the minimum number of characters allowed for values of the target field If present, the value must be an integer. Any attempt to use a value with fewer characters than this number is rejected. This can only be used with a `value-type` of `string`. If not present, no minimum length applies.
`maximum-value-length`	Specifies the maximum number of characters allowed for values of the target field If present, the value must be an integer. Any attempt to use a value with more characters than this number is rejected. This can only be used with a `value-type` of `string`. If not present, no maximum length applies.
`minimum-value-count`	Specifies the minimum number of elements that must be present in an array If present, the value must be an integer. Any attempt to use an array with fewer elements is rejected. This can only be used with an `is-array` value of `required` or `optional`. If not present, no minimum array value count applies.
`maximum-value-count`	Specifies the maximum number of elements that must be present in an array If present, the value must be an integer. Any attempt to use an array with more elements is rejected. This can only be used with an `is-array` value of `required` or `optional`. If not present, no maximum array value count applies.

Note:

When writing JSON objects in a local DB 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