Directory Services 7.4.3

LDAP schema

About LDAP schema

Directory schema, described in RFC 4512, define the kinds of information you find in the directory, and how the information is related.

By default, DS servers conform strictly to LDAPv3 standards for schema definitions and syntax checking. This ensures that data stored is valid and properly formed. Unless your data uses only standard schema present in the server when you install, you must add additional schema definitions to account for the data specific to your applications.

DS servers include many standard schema definitions. You can update and extend schema definitions while DS servers are online. As a result, you can add new applications requiring additional data without stopping your directory service.

The examples that follow focus primarily on the following types of directory schema definitions:

  • Attribute type definitions describe attributes of directory entries, such as givenName or mail.

    Here is an example of an attribute type definition:

    # Attribute type definition
attributeTypes: ( 0.9.2342.19200300.100.1.3 NAME ( 'mail' 'rfc822Mailbox' )
  EQUALITY caseIgnoreIA5Match SUBSTR caseIgnoreIA5SubstringsMatch
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.26{256} X-ORIGIN 'RFC 4524' )

    Attribute type definitions start with an OID, and a short name or names that are easier to remember. The attribute type definition can specify how attribute values should be collated for sorting, and what syntax they use.

    The X-ORIGIN is an extension to identify where the definition originated. When you define your own schema, provide an X-ORIGIN to help track versions of definitions.

    Attribute type definitions indicate whether the attribute is:

    • A user attribute intended to be modified by external applications.

      This is the default, and you can make it explicit with USAGE userApplications.

      The user attributes that are required and permitted on each entry are defined by the entry’s object classes. The server checks what the entry’s object classes require and permit when updating user attributes.

    • An operational attribute intended to be managed by the server for internal purposes.

      You can specify this with USAGE directoryOperation.

      The server does not check whether an operational attribute is allowed by an object class.

    Attribute type definitions differentiate operational attributes with the following USAGE types:

    • USAGE directoryOperation indicates a generic operational attribute.

      Use this type, for example, when creating a last login time attribute.

    • USAGE dSAOperation indicates a DSA-specific operational attribute, meaning an operational attribute specific to the current server.

    • USAGE distributedOperation indicates a DSA-shared operational attribute, meaning an operational attribute shared by multiple servers.

  • Object class definitions identify the attribute types that an entry must have, and may have.

    Here is an example of an object class definition:

    # Object class definition
objectClasses: ( 2.5.6.6 NAME 'person' SUP top STRUCTURAL MUST ( sn $ cn )
  MAY ( userPassword $ telephoneNumber $ seeAlso $ description )
  X-ORIGIN 'RFC 4519' )

    Entries all have an attribute identifying their object classes(es), called objectClass.

    Object class definitions start with an object identifier (OID), and a short name that is easier to remember.

    The definition here says that the person object class inherits from the top object class, which is the top-level parent of all object classes.

    An entry can have one STRUCTURAL object class inheritance branch, such as top → person → organizationalPerson → inetOrgPerson. Entries can have multiple AUXILIARY object classes. The object class defines the attribute types that must and may be present on entries of the object class.

  • An attribute syntax constrains what directory clients can store as attribute values.

    An attribute syntax is identified in an attribute type definition by its OID. String-based syntax OIDs are optionally followed by a number set between braces. The number represents a minimum upper bound on the number of characters in the attribute value. For example, in the attribute type definition shown above, the syntax is 1.3.6.1.4.1.1466.115.121.1.26{256}, IA5 string. An IA5 string (composed of characters from the international version of the ASCII character set) can contain at least 256 characters.

    You can find a table matching attribute syntax OIDs with their human-readable names in RFC 4517, Appendix A. Summary of Syntax Object Identifiers. The RFC describes attribute syntaxes in detail. You can list attribute syntaxes with the dsconfig command.

    If you are trying unsuccessfully to import non-compliant data, clean the data before importing it. If cleaning the data is not an option, read Import Legacy Data.

    When creating attribute type definitions, use existing attribute syntaxes where possible. If you must create your own attribute syntax, then consider the schema extensions in Update LDAP schema.

    Although attribute syntaxes are often specified in attribute type definitions, DS servers do not always check that attribute values comply with attribute syntaxes. DS servers do enforce compliance by default for the following to avoid bad directory data:

    • Certificates

    • Country strings

    • Directory strings

    • JPEG photos

    • Telephone numbers

  • Matching rules define how to compare attribute values to assertion values for LDAP search and LDAP compare operations.

    For example, suppose you search with the filter (uid=bjensen). The assertion value in this case is bjensen.

    DS servers have the following schema definition for the user ID attribute:

    attributeTypes: ( 0.9.2342.19200300.100.1.1 NAME ( 'uid' 'userid' )
 EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch
 SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{256} X-ORIGIN 'RFC 4519' )

    When finding an equality match for your search, servers use the caseIgnoreMatch matching rule to check for user ID attribute values that equal bjensen.

    You can read the schema definitions for matching rules that the server supports by performing an LDAP search:

    $ ldapsearch \
 --hostname localhost \
 --port 1636 \
 --useSsl \
 --usePkcs12TrustStore /path/to/opendj/config/keystore \
 --trustStorePassword:file /path/to/opendj/config/keystore.pin \
 --bindDN uid=kvaughan,ou=People,dc=example,dc=com \
 --bindPassword bribery \
 --baseDn cn=schema \
 --searchScope base \
 "(&)" \
 matchingRules

    Notice that many matching rules support string collation in languages other than English. For the full list of string collation matching rules, refer to Supported locales. For the list of other matching rules, refer to Matching rules.

    Matching rules enable directory clients to compare other values besides strings.

DS servers expose schema over protocol through the cn=schema entry. The server stores the schema definitions in LDIF format files in the db/schema/ directory. When you set up a server, the process copies many definitions to this location.

Update LDAP schema

DS servers allow you to update directory schema definitions while the server is running. You can add support for new types of attributes and entries without interrupting the directory service. DS servers replicate schema definitions, propagating them to other replicas automatically.

You update schema either by:

  • Performing LDAP modify operations while the server is running.

  • Adding schema files to the db/schema/ directory before starting the server.

Before adding schema definitions, take note of the following points:

  • Define DS schema elements in LDIF.

    For examples, refer to the build in schema files in the db/schema/ directory.

  • Add your schema definitions in a file prefixed with a higher number than built-in files, such as 99-user.ldif, which is the default filename when you modify schema over LDAP.

    On startup, the DS server reads schema files in order, sorted alphanumerically. Your definitions likely depend on others that the server should read first.

  • Define a schema element before referencing it in other definitions.

    For example, make sure you define an attribute type before using it in an object class definition.

For an example, refer to Custom schema.

DS servers support the standard LDAP schema definitions described in RFC 4512, section 4.1. They also support the following extensions:

Schema Extensions for All Types
X-DEPRECATED-SINCE

This specifies a release that deprecates the schema element.

Example: X-DEPRECATED-SINCE: 7.4.3

X-ORIGIN

This specifies the origin of a schema element.

Examples:

  • X-ORIGIN 'RFC 4519'

  • X-ORIGIN 'draft-ietf-ldup-subentry'

  • X-ORIGIN 'DS Directory Server'

X-SCHEMA-FILE

This specifies the relative path to the schema file containing the schema element.

Schema definitions are located in /path/to/opendj/db/schema/*.ldif files.

Example: X-SCHEMA-FILE '00-core.ldif'.

X-STABILITY

Used to specify the interface stability of the schema element.

This extension takes one of the following values:

  • Evolving

  • Internal

  • Removed

  • Stable

  • Technology Preview

Schema Extensions for Syntaxes

Extensions to syntax definitions requires additional code to support syntax checking. DS servers support the following extensions for their particular use cases:

X-ENUM

This defines a syntax that is an enumeration of values.

The following attribute syntax description defines a syntax allowing four possible attribute values:

ldapSyntaxes: ( security-label-syntax-oid DESC 'Security Label'
 X-ENUM ( 'top-secret' 'secret' 'confidential' 'unclassified' ) )
X-PATTERN

This defines a syntax based on a regular expression pattern. Valid regular expressions are those defined for java.util.regex.Pattern.

The following attribute syntax description defines a simple, lenient SIP phone URI syntax check:

ldapSyntaxes: ( simple-sip-uri-syntax-oid DESC 'Lenient SIP URI Syntax'
  X-PATTERN '^sip:[a-zA-Z0-9.]+@[a-zA-Z0-9.]+(:[0-9]+)?$' )
X-SUBST

This specifies a substitute syntax to use for one that DS servers do not implement.

The following example substitutes Directory String syntax, OID 1.3.6.1.4.1.1466.115.121.1.15, for a syntax that DS servers do not implement:

ldapSyntaxes: ( non-implemented-syntax-oid DESC 'Not Implemented in DS'
  X-SUBST '1.3.6.1.4.1.1466.115.121.1.15' )
Schema Extensions for Attributes
X-APPROX

X-APPROX specifies a non-default approximate matching rule for an attribute type.

The default is the double metaphone approximate match.

Custom schema

This example updates the LDAP schema while the server is online. It defines a custom enumeration syntax using the attribute type and a custom object class that uses the attribute:

  • A custom enumeration syntax using the X-ENUM extension.

  • A custom attribute type using the custom syntax.

  • A custom object class for entries that have the custom attribute:

$ ldapmodify \
 --hostname localhost \
 --port 1636 \
 --useSsl \
 --usePkcs12TrustStore /path/to/opendj/config/keystore \
 --trustStorePassword:file /path/to/opendj/config/keystore.pin \
 --bindDN uid=admin \
 --bindPassword password <<EOF
dn: cn=schema
changetype: modify
add: ldapSyntaxes
ldapSyntaxes: ( temporary-syntax-oid
  DESC 'Custom enumeration syntax'
  X-ENUM ( 'bronze' 'silver' 'gold' )
  X-ORIGIN 'DS Documentation Examples'
  X-SCHEMA-FILE '99-user.ldif' )
-
add: attributeTypes
attributeTypes: ( temporary-attr-oid
  NAME 'myEnum'
  DESC 'Custom attribute type for'
  SYNTAX temporary-syntax-oid
  USAGE userApplications
  X-ORIGIN 'DS Documentation Examples'
  X-SCHEMA-FILE '99-user.ldif' )
-
add: objectClasses
objectClasses: ( temporary-oc-oid
  NAME 'myEnumObjectClass'
  DESC 'Custom object class for entries with a myEnum attribute'
  SUP top
  AUXILIARY
  MAY myEnum
  X-ORIGIN 'DS Documentation Examples'
  X-SCHEMA-FILE '99-user.ldif' )

EOF

# MODIFY operation successful for DN cn=schema

Notice the follow properties of this update to the schema definitions:

  • The ldapSyntaxes definition comes before the attributeTypes definition that uses the syntax.

    The attributeTypes definition comes before the objectClasses definition that uses the attribute type.

  • Each definition has a temporary OID of the form temporary-*-oid.

    While you develop new schema definitions, temporary OIDs are fine. Get permanent, correctly assigned OIDs before using schema definitions in production.

  • Each definition has a DESC (description) string intended for human readers.

  • Each definition specifies its origin with the extension X-ORIGIN 'DS Documentation Examples'.

  • Each definition specifies its schema file with the extension X-SCHEMA-FILE '99-user.ldif'.

  • The syntax definition has no name, as it is referenced internally by OID only.

  • X-ENUM ( 'bronze' 'silver' 'gold' ) indicates that the syntax allows three values, bronze, silver, gold.

    DS servers reject other values for attributes with this syntax.

  • The attribute type named myEnum has these properties:

    • It uses the enumeration syntax, SYNTAX temporary-syntax-oid.

    • It can only have one value at a time, SINGLE-VALUE.

      The default, if you omit SINGLE-VALUE, is to allow multiple values.

    • It is intended for use by user applications, USAGE userApplications.

  • The object class named myEnumObjectClass has these properties:

    • Its parent for inheritance is the top-level object class, SUP top.

      top is the abstract parent of all structural object class hierarchies, so all object classes inherit from it.

    • It is an auxiliary object class, AUXILIARY.

      Auxiliary object classes are used to augment attributes of entries that already have a structural object class.

    • It defines no required attributes (no MUST).

    • It defines one optional attribute which is the custom attribute, MAY myEnum.

After adding the schema definitions, you can add the attribute to an entry as shown in the following example:

$ ldapmodify \
 --hostname localhost \
 --port 1636 \
 --useSsl \
 --usePkcs12TrustStore /path/to/opendj/config/keystore \
 --trustStorePassword:file /path/to/opendj/config/keystore.pin \
 --bindDN uid=admin \
 --bindPassword password <<EOF
dn: uid=bjensen,ou=People,dc=example,dc=com
changetype: modify
add: objectClass
objectClass: myEnumObjectClass
-
add: myEnum
myEnum: silver

EOF

# MODIFY operation successful for DN uid=bjensen,ou=People,dc=example,dc=com

As shown in the following example, the attribute syntax prevents users from setting an attribute value that is not specified in your enumeration:

$ ldapmodify \
 --hostname localhost \
 --port 1636 \
 --useSsl \
 --usePkcs12TrustStore /path/to/opendj/config/keystore \
 --trustStorePassword:file /path/to/opendj/config/keystore.pin \
 --bindDN uid=admin \
 --bindPassword password <<EOF
dn: uid=bjensen,ou=People,dc=example,dc=com
changetype: modify
replace: myEnum
myEnum: wrong value

EOF

# The LDAP modify request failed: 21 (Invalid Attribute Syntax)
# Additional Information:  When attempting to modify entry uid=bjensen,ou=People,dc=example,dc=com to replace the set of values for attribute myEnum, value "wrong value" was found to be invalid according to the associated syntax: The provided value "wrong value" cannot be parsed because it is not allowed by enumeration syntax with OID "temporary-syntax-oid"

For more examples, read the built-in schema definition files in the db/schema/ directory.

Schema and JSON

DS software has the following features for working with JSON objects:

  • RESTful HTTP access to directory services

    If you have LDAP data, but HTTP client applications want JSON over HTTP instead, DS software can expose your LDAP data as JSON resources over HTTP to REST clients.

    There is no requirement to change LDAP schema definitions before using this feature. To get started, refer to HDAP API reference.

  • JSON syntax LDAP attributes

    If you have LDAP client applications that store JSON in the directory, you can define LDAP attributes that have Json syntax.

    The following schema excerpt defines an attribute called json with case-insensitive matching:

    attributeTypes: ( json-attribute-oid NAME 'json'
 SYNTAX 1.3.6.1.4.1.36733.2.1.3.1 EQUALITY caseIgnoreJsonQueryMatch
 X-ORIGIN 'DS Documentation Examples' )

    Notice that the JSON syntax OID is 1.3.6.1.4.1.36733.2.1.3.1. The definition above uses the (default) caseIgnoreJsonQueryMatch matching rule for equality. As explained later in this page, you might want to choose different matching rules for your JSON attributes.

    When DS servers receive update requests for Json syntax attributes, they expect valid JSON objects. By default, Json syntax attribute values must comply with The JavaScript Object Notation (JSON) Data Interchange Format, described in RFC 7159. You can use the advanced core schema configuration option json-validation-policy to have the server be more lenient in what it accepts, or to disable JSON syntax checking.

  • Configurable indexing for JSON attributes

    When you store JSON attributes in the directory, you can index every field in each JSON attribute value, or you can index only what you use.

    As for other LDAP attributes, the indexes depend on the matching rule defined for the JSON syntax attribute.

DS servers treat JSON syntax attribute values as objects. Two JSON values may be considered equivalent despite differences in their string representations. The following JSON objects can be considered equivalent because each field has the same value. Their string representations are different, however:

[
 { "id": "bjensen", "given-name": "Barbara", "surname": "Jensen" },
 {"surname":"Jensen","given-name":"Barbara","id":"bjensen"}
]

Unlike other objects with their own LDAP attribute syntaxes, such as X.509 certificates, two JSON objects with completely different structures (different field names and types) are still both JSON. Nothing in the JSON syntax alone tells the server anything about what a JSON object must and may contain.

When defining LDAP schema for JSON attributes, it helps therefore to understand the structure of the expected JSON. Will the attribute values be arbitrary JSON objects, or JSON objects whose structure is governed by some common schema? If a JSON attribute value is an arbitrary object, you can do little to optimize how it is indexed or compared. If the value is a structured object, however, you can configure optimizations based on the structure.

For structured JSON objects, the definition of JSON object equality is what enables you to pick the optimal matching rule for the LDAP schema definition. The matching rule determines how the server indexes the attribute, and how the server compares two JSON values for equality. You can define equality in the following ways:

  • Two JSON objects are equal if all fields have the same values.

    By this definition, {"a": 1, "b": true} equals {"b":true,"a":1}. However, {"a": 1, "b": true} and {"a": 1, "b": "true"} are different.

  • Two JSON objects ` equal if some fields have the same values. Other fields are ignored when comparing for equality.

    For example, take the case where two JSON objects are considered equal if they have the same "_id" values. By this definition, {"_id":1,"b":true} equals {"_id":1,"b":false}. However, {"_id":1,"b":true} and {"_id":2,"b":true} are different.

    DS servers have built-in matching rules for the case where equality means "_id" values are equal. If the fields to compare are different from "_id", you must define your own matching rule and configure a custom schema provider that implements it. This following table helps you choose a JSON equality matching rule:

JSON Content Two JSON Objects are Equal if…​ Use One of These Matching Rules

Arbitrary (any valid JSON is allowed)

All fields have the same values.

caseExactJsonQueryMatch
caseIgnoreJsonQueryMatch

Structured

All fields have the same values.

caseExactJsonQueryMatch
caseIgnoreJsonQueryMatch

Structured

One or more other fields have the same values.

Additional fields are ignored when comparing for equality.

When using this matching rule, create a custom json-equality-matching-rule Schema Provider. The custom schema provider must include all the necessary properties and reference the custom field(s).

Refer to JSON Equality Matching Rule Index.

When you choose an equality matching rule in the LDAP attribute definition, you are also choosing the default that applies in an LDAP search filter equality assertion. For example, caseIgnoreJsonQueryMatch works with filters such as "(json=id eq 'bjensen')".

DS servers also implement JSON ordering matching rules for determining the relative order of two JSON values using a custom set of rules. You can select which JSON fields should be used for performing the ordering match. You can also define whether those fields that contain strings should be normalized before comparison by trimming white space or ignoring case differences. DS servers can implement JSON ordering matching rules on demand when presented with an extended server-side sort request, as described in Server-Side Sort. If, however, you define them statically in your LDAP schema, then you must implement them by creating a custom json-ordering-matching-rule Schema Provider. For details about the json-ordering-matching-rule object’s properties, refer to JSON Ordering Matching Rule.

For examples showing how to add LDAP schema for new attributes, refer to Update LDAP Schema. For examples showing how to index JSON attributes, refer to Custom Indexes for JSON.

Import legacy data

By default, DS servers accept data that follows the schema for allowable and rejected data. You might have legacy data from a directory service that is more lenient, allowing non-standard constructions such as multiple structural object classes per entry, not checking attribute value syntax, or even not respecting schema definitions.

For example, when importing data with multiple structural object classes defined per entry, you can relax schema checking to warn rather than reject entries having this issue:

$ dsconfig \
 set-global-configuration-prop \
 --hostname localhost \
 --port 4444 \
 --bindDN uid=admin \
 --bindPassword password \
 --set single-structural-objectclass-behavior:warn \
 --usePkcs12TrustStore /path/to/opendj/config/keystore \
 --trustStorePassword:file /path/to/opendj/config/keystore.pin \
 --no-prompt

You can allow attribute values that do not respect the defined syntax:

$ dsconfig \
 set-global-configuration-prop \
 --hostname localhost \
 --port 4444 \
 --bindDN uid=admin \
 --bindPassword password \
 --set invalid-attribute-syntax-behavior:warn \
 --usePkcs12TrustStore /path/to/opendj/config/keystore \
 --trustStorePassword:file /path/to/opendj/config/keystore.pin \
 --no-prompt

You can even turn off schema checking altogether. Only turn off schema checking when you are absolutely sure that the entries and attributes already respect the schema definitions:

$ dsconfig \
 set-global-configuration-prop \
 --hostname localhost \
 --port 4444 \
 --bindDN uid=admin \
 --bindPassword password \
 --set check-schema:false \
 --usePkcs12TrustStore /path/to/opendj/config/keystore \
 --trustStorePassword:file /path/to/opendj/config/keystore.pin \
 --no-prompt

Turning off schema checking can potentially boost import performance.

Standard schema

DS servers provide many standard schema definitions. For full descriptions, refer to the Schema Reference. Find the definitions in LDIF files in the /path/to/opendj/db/schema/ directory:

File Description

00-core.ldif

Schema definitions for the following Internet-Drafts, RFCs, and standards:

01-pwpolicy.ldif

Schema for draft-behera-ldap-password-policy (Draft 09), which defines a mechanism for storing password policy information in an LDAP directory server.

02-config.ldif

This file contains the attribute type and objectclass definitions for use with the server configuration.

03-changelog.ldif

Schema for draft-good-ldap-changelog, which defines a mechanism for storing information about changes to directory server data.

03-rfc2713.ldif

Schema for RFC 2713, which defines a mechanism for storing serialized Java objects in the directory server.

03-rfc2714.ldif

Schema for RFC 2714, which defines a mechanism for storing CORBA objects in the directory server.

03-rfc2739.ldif

Schema for RFC 2739, which defines a mechanism for storing calendar and vCard objects in the directory server.

Be aware that the definition in RFC 2739 contains a number of errors. This schema file has been altered from the standard definition to fix a number of those problems.

03-rfc2926.ldif

Schema for RFC 2926, which defines a mechanism for mapping between Service Location Protocol (SLP) advertisements and LDAP.

03-rfc3112.ldif

Schema for RFC 3112, which defines the authentication password schema.

03-rfc3712.ldif

Schema for RFC 3712, which defines a mechanism for storing printer information in the directory server.

03-uddiv3.ldif

Schema for RFC 4403, which defines a mechanism for storing UDDIv3 information in the directory server.

04-rfc2307bis.ldif

Schema for draft-howard-rfc2307bis, which defines a mechanism for storing naming service information in the directory server.

05-rfc4876.ldif

Schema for RFC 4876, which defines a schema for storing Directory User Agent (DUA) profiles and preferences in the directory server.

05-samba.ldif

Schema required when storing Samba user accounts in the directory server.

05-solaris.ldif

Schema required for Solaris and OpenSolaris LDAP naming services.

06-compat.ldif

Backwards-compatible schema for use in the server configuration.
Copyright © 2010-2024 ForgeRock, all rights reserved.