Schema This chapter describes how to manage Lightweight Directory Access Protocol (LDAP) schema definitions for directory data. In this chapter you will learn to: Understand LDAP schemas including the schema definitions delivered with OpenDJ directory server Change and extend OpenDJ LDAP schemas Relax schema checking when troubleshooting data that do not conform to schema definitions Schema definitions describe the data, and especially the object classes and attribute types that can be stored in the directory. By default OpenDJ conforms strictly to LDAPv3 standards pertaining to schema definitions and attribute syntax checking, ensuring that data stored is valid and properly formed. Unless your data use only standard schema present in OpenDJ when you install, then you must add additional schema definitions to account the data your applications stored. Out of the box, OpenDJ comes with many standard schema definitions. In addition you can update and extend schema definitions while OpenDJ is online. As a result you can add new applications requiring additional data without stopping your directory service.

Directory schema, described in RFC 4512, defines the kinds of information you find in the directory, and can define how the information are related. This chapter focuses primarily on two 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 object identifier (OID), and generally a short name or names that are easier to remember than the OID. 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, you likely want to provide an X-ORIGIN to help you to track versions of definitions, and where the definitions came from. Object class definitions identify the attribute types that an entry must have, and may have. Examples of object classes include person and organizationalUnit. 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, called objectClass. Object class definitions start with an object identifier (OID), and generally a short name that is easier to remember than the OID. 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. When you view the objectclass attribute values on an entry, you see the list of object classes that the entry takes. An entry can have one STRUCTURAL object class inheritance branch, such as top - person - organizationalPerson - inetOrgPerson. Yet entries can have multiple AUXILIARY object classes. The object class then defines the attribute types that must be included, and the attribute types that may be included on entries having 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, that 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}. The syntax is an IA5 string (composed of characters from the international version of the ASCII character set) that 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. Alternatively, you can see the attribute syntaxes that OpenDJ supports by opening the OpenDJ Control Panel and browsing to Schema > Manage Schema > Attribute Syntaxes. You can also list them by using the dsconfig command. Although attribute syntaxes are often specified in attribute type definitions, directory servers do not always check that attribute values comply with attribute syntaxes. OpenDJ directory server does tend to enforce compliance by default, in particular for certificates, country strings, directory strings, JPEG photos, and telephone numbers. The aim is to avoid accumulating garbage in your directory data. If you are trying unsuccessfully to import non-compliant data from a more lenient directory server, you can either clean the data before importing it, or if cleaning the data is not an option, read . When creating your own attribute type definitions, use existing attribute syntaxes where possible. If you must create your own attribute syntax, then consider the extensions in . Matching rules determine how the directory server compares 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. OpenDJ has 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, OpenDJ uses the caseIgnoreMatch matching rule to check for user ID attribute values that equal bjensen without regard to case. You can see the matching rules that OpenDJ supports by opening the OpenDJ Control Panel and browsing to Schema > Manage Schema > Matching Rules. Notice that many matching rules support string collation in languages other than English. You can also list matching rules by using the dsconfig command. As you can read in examples like, Search: List Active Accounts, OpenDJ matching rules enable directory clients to do more interesting searches than simply comparing strings. That example shows how to search for users who have authenticated in the last three months. OpenDJ exposes schema over protocol through the cn=schema entry. OpenDJ stores the schema definitions corresponding to the entry in LDIF under the config/schema/ directory. Many standard definitions and definitions pertaining to the server configuration are included at installation time.

Replication Schema definitions OpenDJ directory server is designed to permit updating the list of directory schema definitions while the server is running. As a result you can add support for new applications that require new attributes or new kinds of entries without interrupting the directory service. OpenDJ also replicates schema definitions, so the schema you add on one replica is propagated to other replicas without you having to intervene manually. As it is easy to introduce typos into schema definitions, the best way to start defining your own schema is with the OpenDJ Control Panel. Open the Control Panel > Schema > Manage Schema window to get started creating your custom object classes and attribute types. As object classes reference attribute types, you first create custom attribute types, and then create the object class that references the attribute types. Create a custom attribute type through the New Attribute window. Using the New Object Class window, create an auxiliary object class that allows your new custom attribute type. You set the type to Auxiliary under Extra Options. When you finish, the schema changes show up by default in the file config/schema/99-user.ldif. Notice that the file name starts with a number, 99. This number is larger than the numbers prefixing other schema file names. In fact, OpenDJ reads the schema files in sorted order, reading schema definitions as they occur. If OpenDJ reads a schema definition for an object class before it has read the definitions of the attribute types mentioned in the object class definition, then it displays an error. Therefore, when naming your schema file, make sure the name appears in the sorted list of file names after all the schema files containing definitions that your schema definitions depends on. The default file name for your schema, 99-user.ldif, ensures that your definitions load only after all of the schema files installed by default. You can create this file in the lab using the Control Panel, and then apply the definitions in production by adapting the content for use with the ldapmodify command, for example. $ cat config/schema/99-user.ldif dn: cn=schema objectClass: top objectClass: ldapSubentry objectClass: subschema cn: schema attributeTypes: ( temporary-fake-attr-id NAME 'myCustomAttribute' EQUALITY case IgnoreMatch ORDERING caseIgnoreOrderingMatch SUBSTR caseIgnoreSubstrings Match SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 USAGE userApplications ) objectClasses: ( temporary-fake-oc-id NAME 'myCustomObjClass ' SUP top AUXILIARY MAY myCustomAttribute ) modifiersName: cn=Directory Manager,cn=Root DNs,cn=config modifyTimestamp: 20110620095948Z To test your schema definition, add the object class and attribute to an entry. $ cat custom-attr.ldif dn: uid=bjensen,ou=People,dc=example,dc=com changetype: modify add: objectClass objectClass: myCustomObjClass - add: myCustomAttribute myCustomAttribute: Testing 1, 2, 3... $ ldapmodify \ --port 1389 \ --bindDN "cn=Directory Manager" \ --bindPassword password \ --filename custom-attr.ldif Processing MODIFY request for uid=bjensen,ou=People,dc=example,dc=com MODIFY operation successful for DN uid=bjensen,ou=People,dc=example,dc=com $ ldapsearch \ --port 1389 \ --baseDN dc=example,dc=com \ uid=bjensen \ myCustomAttribute dn: uid=bjensen,ou=People,dc=example,dc=com myCustomAttribute: Testing 1, 2, 3... In addition to supporting the standard schema definitions that are described in RFC 4512, section 4.1, OpenDJ also supports the following extensions that you can use when adding your own definitions. Schema Schema definition extensions X-ORIGIN Used to specify the origin of a schema element. Examples include X-ORIGIN 'RFC 4519', X-ORIGIN 'draft-ietf-ldup-subentry', and X-ORIGIN 'OpenDJ Directory Server'. X-SCHEMA-FILE Used to specify the relative path to the schema file containing the schema element such as X-SCHEMA-FILE '00-core.ldif'. Schema definitions are located by default in /path/to/opendj/config/schema/*.ldif files. Schema Schema definition extensions X-ENUM Used to define a syntax that is an enumeration of values. The following attribute syntax description defines a syntax allowing four possible attribute values for example. ldapSyntaxes: ( security-label-syntax-oid DESC 'Security Label' X-ENUM ( 'top-secret' 'secret' 'confidential' 'unclassified' ) ) X-PATTERN Used to define a syntax based on a regular expression pattern, where 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 Used as a fallback to substitute a defined syntax for one that OpenDJ does not implement. The following example substitutes Directory String syntax, which has OID 1.3.6.1.4.1.1466.115.121.1.15, for a syntax that OpenDJ does not implement. ldapSyntaxes: ( non-implemented-syntax-oid DESC 'Not Implemented in OpenDJ' X-SUBST '1.3.6.1.4.1.1466.115.121.1.15' ) Schema Schema definition extensions X-APPROX X-APPROX is used to specify the approximate matching rule to use for a given attribute type when not using the default, which is the double metaphone approximate match.

Schema Legacy data By default, OpenDJ accepts data that follows the standards in terms of what is allowed and what is rejected. 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 opendj.example.com \ --port 4444 \ --bindDN "cn=Directory Manager" \ --bindPassword password \ --set single-structural-objectclass-behavior:warn \ --trustAll \ --no-prompt You can allow attribute values that do not respect the defined syntax with the dsconfig command as well. $ dsconfig \ set-global-configuration-prop \ --hostname opendj.example.com \ --port 4444 \ --bindDN "cn=Directory Manager" \ --bindPassword password \ --set invalid-attribute-syntax-behavior:warn \ --trustAll \ --no-prompt You can even turn off schema checking altogether, although turning off schema checking only really makes sense when you are absolutely sure that the entries and attribute values respect the schema definitions, and you simply want to turn off schema checking temporarily to speed up import processing. $ dsconfig \ set-global-configuration-prop \ --hostname opendj.example.com \ --port 4444 \ --bindDN "cn=Directory Manager" \ --bindPassword password \ --set check-schema:false \ --trustAll \ --no-prompt