Note: this component is designated "advanced", which means that objects of this type are not expected to be created or altered in most environments. If you believe that such a change is necessary, you may want to contact support in order to understand the potential impact of that change.
Note: this component stores cluster-wide configuration data and is mirrored across all servers in the topology within the the same cluster.
Note: changes to cluster-wide configuration objects are immediately and automatically mirrored across all servers within the same cluster, so offline changes are not supported.
JSON Field Constraints may be used to define a number of constraints that the server will impose for an indicated field in a JSON object that may be stored in a specified LDAP attribute. It also defines additional properties that the server may use when interacting with values of the target field, including indicating whether backends should index and/or tokenize extra values for that field.
↓Relations to This Component
↓Properties
↓dsconfig Usage
The following components have a direct composition relation to JSON Field Constraints:
The properties supported by this managed object are as follows:
| Basic Properties: | Advanced Properties: |
|---|---|
| ↓ description | ↓ index-entry-limit |
| ↓ json-field | ↓ prime-index |
| ↓ value-type | ↓ cache-mode |
| ↓ is-required | ↓ tokenize-values |
| ↓ is-array | ↓ allowed-value |
| ↓ allow-null-value | ↓ allowed-value-regular-expression |
| ↓ allow-empty-object | ↓ minimum-numeric-value |
| ↓ index-values | ↓ maximum-numeric-value |
| ↓ minimum-value-length | |
| ↓ maximum-value-length | |
| ↓ minimum-value-count | |
| ↓ maximum-value-count |
| Description | A description for this JSON Field Constraints |
| Default Value | None |
| Allowed Values | A string |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
| Description | The full name of the JSON field to which these constraints apply. For a top-level field, this may simply be the name of that field. For fields that exist inside JSON objects nested inside the outer object, the complete path to the target field must be provided using periods as delimiters between levels of hierarchy (for example, in order to target a field called zipCode that may exist inside a JSON object that is the value of a field called address, the field name would be specified as address.zipCode). If any field has a name that contains a period, then that field name must be placed in quotation marks. For example, a json-field value of name.last without any quotation marks refers to a field called last inside of an object that is itself the value of a field called name, while a json-field value of "name.last" with the quotation marks refers to a single field called name.last. |
| Default Value | None |
| Allowed Values | A string |
| Multi-Valued | No |
| Required | Yes |
| Admin Action Required | None. Modification requires no further action |
| Description | The data type that will be required for values of the target field. |
| Default Value | None |
| Allowed Values | any - The target field may have any kind of value. boolean - The target field will only be permitted to have values of true or false. integer - The target field will only be permitted to have values that are JSON numbers that exactly represent integer values (i.e., numbers with no fractional component). null - The target field will only be permitted to have values that are the JSON null value. number - The target field will only be permitted to have values that are JSON numbers, optionally including a fractional component. object - The target field will only be permitted to have values that are JSON objects. Separate JSON Field Constraints definitions may be used to define constraints for fields within these objects. string - The target field will only be permitted to have values that are JSON strings. |
| Multi-Valued | No |
| Required | Yes |
| Admin Action Required | None. Modification requires no further action |
| Description | Indicates whether the target field must be present in JSON objects stored as values of the associated attribute type. |
| Default Value | false |
| Allowed Values | true false |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
| Description | Indicates whether the value of the target field may be an array of values rather than a single value. If this property is set to "required" or "optional", then the constraints defined for this field will be applied to each element of the array. |
| Default Value | prohibited |
| Allowed Values | required - The value of the target field must be an array of elements of the specified value-type. optional - The value of the target field may be an array of elements of the specified value-type, or it may be a single value of the specified value-type. prohibited - The value of the target field must not be an array, but must be a single value of the specified value-type. |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
| Description | Indicates whether the target field may have a value that is the JSON null value as an alternative to a value (or array of values) of the specified value-type. |
| Default Value | false |
| Allowed Values | true false |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
| Description | Indicates whether the target field may have a value that is an empty JSON object (i.e., a JSON object with zero fields). This may only be set to true if value-type property is set to object. |
| Default Value | false |
| Allowed Values | true false |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
| Description | Indicates whether backends that support JSON indexing should maintain an index for values of the target field. An index may be able to improve the performance of some searches containing JSON object filters of type equals, equalsAny, greaterThan, lessThan, or substring. However, maintaining an index will increase the size of the database on disk, the amount of memory required to fully cache its contents, and the cost of updating the index for write operations. Indexing may only be enabled for fields with a value-type of boolean, integer, null, or string. |
| Default Value | false |
| Allowed Values | true false |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | When adding a new JSON field index, you may need to use the rebuild-index tool to initialize the index based on existing data in the backend before the server will use or maintain that index. However, if the server can determine that either the backend is empty or the associated JSON field has never been used in any entries in the backend, then the new index may automatically be considered trusted. To determine whether an index needs to be initialized with the rebuild-index tool, use the command:
dbtest list-database-containers --backendID {backendID}
If the "Index Status" field has a value of "TRUSTED", then the server has determined that the JSON field is not used in the backend and it is not necessary to use rebuild-index to initialize that index. If the "Index Status" field has a different value (e.g., "UNTRUSTED" or "NEW"), then it needs to be initialized with the rebuild-index tool before it can be used. |
index-entry-limit (Advanced Property)
| Description | The maximum number of entries that may contain a particular value for the target field before the server will stop maintaining the index for that value. Note that JSON indexes will not be stored as exploded indexes. If a JSON index is configured with a large index entry limit, then this may require the backend to store a large candidate list for values that are present in a large number of entries. |
| Default Value | The backend's default index-entry-limit value will be used. |
| Allowed Values | An integer value. Lower limit is 1. |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | When increasing the index-entry-limit for a field that may contain values that have already exceeded the previous limit, you must use the rebuild-index tool (or export the contents of the backend to LDIF and re-import the data) before the new limit will be used for those values. |
prime-index (Advanced Property)
| Description | Indicates whether backends that support database priming should load the contents of the associated JSON index into memory whenever the backend is opened. The prime-index property will be ignored by backends with prime-all-indexes set to true. In that case, the server will attempt to prime all JSON indexes when opening the backend. |
| Default Value | false |
| Allowed Values | true false |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
cache-mode (Advanced Property)
| Description | Specifies the behavior that the server should exhibit when caching data for the associated JSON index. This can be useful in environments in which the system does not have enough memory to fully cache the entire data set, as it makes it possible to prioritize which data is the most important to keep in memory. |
| Default Value | The backend's default cache-mode value will be used. |
| Allowed Values | cache-keys-and-values - The server will attempt to hold the entire set of data for this index in memory. This includes not only the structure of the B-tree database for the index, but also the lists of entry IDs that match each of the indexed values.
If this index is to be primed and prime-index-internal-nodes-only is set to false, then priming will load the complete data for this index into memory. If prime-index-internal-nodes-only is set to true, then only the internal structure of the index database will be loaded into memory when the backend is opened, but the matching entry ID lists will be gradually loaded into memory as the data is accessed. cache-keys-only - The server will only attempt to hold the internal nodes of the index database in memory. This includes the index keys and any entry ID lists for keys that match four or fewer entries. In deployments on systems that do not have enough memory to fully cache the entire contents of the backend, caching at least the internal nodes may allow for substantially better performance than if no caching is performed at all. If this index is to be primed, then priming will only load the internal nodes for this index into memory, regardless of the value for the prime-internal-nodes-only property. no-caching - The server will not attempt to cache any information for the associated JSON index in memory. Further, no priming will be performed for this database, regardless of the value of the prime-index property. |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
tokenize-values (Advanced Property)
| Description | Indicates whether the backend should attempt to assign a compact token for each distinct value for the target field in an attempt to reduce the encoded size of the field in JSON objects. These tokens would be assigned prior to using any from the token set used for automatic compaction of some JSON string values. Value tokenization should only be enabled for fields with a value-type of string that are expected to have a relatively small number of distinct values that are shared across a large number of entries. |
| Default Value | false |
| Allowed Values | true false |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
allowed-value (Advanced Property)
| Description | Specifies an explicit set of string values that will be the only values permitted for the target field. If a set of allowed values is defined, then the server will reject any attempt to store a JSON object with a value for the target field that is not included in that set. An explicitly-defined set of allowed values may only be configured if the value-type property is set to string. If a set of allowed values is configured, then it is also recommended that tokenize-values be set to true so that those values can be represented more efficiently in the internal encoded representation of JSON objects without consuming any from the token set used for automatic compaction of some JSON string values. |
| Default Value | None |
| Allowed Values | A string |
| Multi-Valued | Yes |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
allowed-value-regular-expression (Advanced Property)
| Description | Specifies an explicit set of regular expressions that may be used to restrict the set of values that may be used for the target field. If a set of allowed value regular expressions is defined, then the server will reject any attempt to store a JSON object with a value for the target field that does not match at least one of those regular expressions. An explicitly-defined set of allowed value regular expressions may only be configured if the value-type property is set to string. If one or more values are provided for this property, then they must represent valid regular expressions that is compatible for use with the java.util.regex.Pattern class. Regular expression matching is case sensitive by default. However, the string "(?i)" may be placed at the beginning of the regular expression to indicate that matching should be case insensitive. |
| Default Value | None |
| Allowed Values | A string |
| Multi-Valued | Yes |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
minimum-numeric-value (Advanced Property)
| Description | Specifies the smallest numeric value that may be used as the value for the target field. If configured, then the server will reject any attempt to store a JSON object with a value for the target field that is less than that minimum numeric value. A minimum numeric value may only be configured if the value-type property is set to integer or number. If a value is provided for this property, then it must represent a valid JSON number (although it does not necessarily need to be an integer). |
| Default Value | None |
| Allowed Values | A string |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
maximum-numeric-value (Advanced Property)
| Description | Specifies the largest numeric value that may be used as the value for the target field. If configured, then the server will reject any attempt to store a JSON object with a value for the target field that is greater than that maximum numeric value. A maximum numeric value may only be configured if the value-type property is set to integer or number. If a value is provided for this property, then it must represent a valid JSON number (although it does not necessarily need to be an integer). |
| Default Value | None |
| Allowed Values | A string |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
minimum-value-length (Advanced Property)
| Description | Specifies the smallest number of characters that may be present in string values of the target field. If configured, then the server will reject any attempt to store a JSON object with a value for the target field that is shorter than that minimum value length. A minimum value length may only be configured if the value-type property is set to string. |
| Default Value | None |
| Allowed Values | An integer value. Lower limit is 0. |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
maximum-value-length (Advanced Property)
| Description | Specifies the largest number of characters that may be present in string values of the target field. If configured, then the server will reject any attempt to store a JSON object with a value for the target field that is longer than that maximum value length. A maximum value length may only be configured if the value-type property is set to string. |
| Default Value | None |
| Allowed Values | An integer value. Lower limit is 0. |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
minimum-value-count (Advanced Property)
| Description | Specifies the smallest number of elements that may be present in an array of values for the target field. If configured, then the server will reject any attempt to store a JSON object with a value for the target field that is an array with fewer than this number of elements. A minimum value count may only be configured if the is-array property is set to required or optional. |
| Default Value | None |
| Allowed Values | An integer value. Lower limit is 0. |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
maximum-value-count (Advanced Property)
| Description | Specifies the largest number of elements that may be present in an array of values for the target field. If configured, then the server will reject any attempt to store a JSON object with a value for the target field that is an array with more than this number of elements. A maximum value count may only be configured if the is-array property is set to required or optional. |
| Default Value | None |
| Allowed Values | An integer value. Lower limit is 0. |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
To list the configured JSON Field Constraints:
dsconfig list-json-field-constraints
[--property {propertyName}] ...
To view the configuration for an existing JSON Field Constraints:
dsconfig get-json-field-constraints-prop
--json-field {name}
--attribute-type {name}
[--tab-delimited]
[--script-friendly]
[--property {propertyName}] ...
To update the configuration for an existing JSON Field Constraints:
dsconfig set-json-field-constraints-prop
--json-field {name}
--attribute-type {name}
(--set|--add|--remove) {propertyName}:{propertyValue}
[(--set|--add|--remove) {propertyName}:{propertyValue}] ...
To create a new JSON Field Constraints:
dsconfig create-json-field-constraints
--json-field {name}
--attribute-type {name}
--set value-type:{propertyValue}
[--set {propertyName}:{propertyValue}] ...
To delete an existing JSON Field Constraints:
dsconfig delete-json-field-constraints
--json-field {name}
--attribute-type {name}