Chapter 3. Designing the directory schema
The directory schema describes the types of data in the directory. You can determine which schema to use when you know the representation of data stored in the directory. Each data element is mapped to an LDAP attribute, and related elements are gathered into LDAP object classes, during the schema design process. A well-designed schema helps to maintain the integrity of the directory data.
3.1. Overview of the schema design process
You can select and define the object classes and attributes to represent the entries stored by Directory Server during the schema design process. The following steps are performed during schema design process:
- Choosing predefined schema elements to meet data requirements.
- Extending the standard Directory Server schema to define new elements to meet the requirements.
- Planning the schema maintenance.
You can use the existing schema elements defined in the standard schema provided by Directory Server. Standard schema elements help to ensure compatibility with directory-enabled applications. The schema is reviewed and agreed to by a wide number of directory users because the schema is based on the LDAP standard.
3.2. Standard schema
The directory schema maintains the integrity of the data stored in the directory by setting constraints on the size, range, and format of data values. The schema identifies different types of entries the directory contains (like people, devices, and organizations) and the attributes available for each entry.
The predefined schema in Directory Server contains both the standard LDAP schema and application-specific schema to support the features of the server. You can extend the schema by adding new object classes and attributes to accommodate the unique needs of the directory.
3.2.1. Schema format
The schema format of Directory Server is built on version 3 of the LDAP protocol. This protocol requires Directory Server to publish their schema through LDAP itself allowing directory client applications to retrieve the schema programmatically and adapt their behavior. You can find the global set of schema for Directory Server in the cn=schema entry.
The Directory Server schema is different from the LDAPv3 schema, because it uses its proprietary object classes and attributes. Additionally, it uses a private field in the schema entries called X-ORIGIN 389 Directory Server which describes where the schema entry was defined originally.
When you define a schema entry in the standard LDAPv3 schema, the X-ORIGIN 389 Directory Server field refers to RFC 2252. If the entry is defined by Red Hat for the Directory Server’s use, the X-ORIGIN 389 Directory Server field contains the value 389 Directory Server. For example, the standard person object class appears in the schema:
# objectclasses: ( 2.5.6.6 NAME 'person' DESC 'Standard Person Object Class' SUP top MUST (objectclass $ sn $ cn) MAY (description $ seeAlso $ telephoneNumber $ userPassword) X-ORIGIN 'RFC 2252' )
This schema entry states:
-
The object identifier(OID) for the class (
2.5.6.6) -
The name of the object class (
person) -
Description of the class (
Standard Person) -
The required attributes (
objectclass, sn, and cn) -
The optional attributes (
description,seeAlso,telephoneNumber, anduserPassword)
3.2.2. Standard attributes
Attributes contain specific data elements such as a name or a fax number. Directory Server represents data as attribute-data pairs which is a descriptive schema attribute associated with a specific piece of information. These are also called attribute-value assertions or AVAs.
For example, the directory can store a piece of data, such as a person’s name, in a pair with the standard attribute. An entry for a person named Babs Jensen has the attribute-data pair cn: Babs Jensen.
The entire entry is represented as a series of attribute-data pairs. The entire entry for Babs Jensen is as follows:
dn: uid=bjensen,ou=people,dc=example,dc=com objectClass: top objectClass: person objectClass: organizationalPerson objectClass: inetOrgPerson cn: Babs Jensen sn: Jensen givenName: Babs givenName: Barbara mail: bjensen@example.com
Each attribute definition in the schema contains the following information:
- A unique name
- An object identifier (OID) for the attribute
- A text description of the attribute
- The OID of the attribute syntax
Indications for the following:
- The attribute is single-valued or multi-valued
- The attribute is for the directory’s own use
- The origin of the attribute
- Additional matching rules associated with the attribute.
The cn attribute definition appears in the schema as follows:
attributetypes: ( 2.5.4.3 NAME 'cn' DESC 'commonName Standard Attribute'
SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 )Using the attribute’s syntax, you can define the format of the values that can be stored in the attribute. The Directory Server supports all standard attribute syntaxes.
Additional resources
3.2.3. Standard object classes
An object class represents a real object, such as a person or a fax machine. It is used to group related information. You must identify an object class and its attributes in the schema before you use the object classes. The directory recognizes a standard list of object classes by default.
Each directory entry belongs to at least one object classes. When you place an object class identified in the schema on an entry, it informs the Directory Server that the entry can have a specific set of attribute values and must have another smaller set of required attribute values.
The following information is available in object class definitions:
- A unique name
- An object identifier (OID)
- A set of mandatory attributes
- A set of either allowed or optional attributes
The standard person object class in the schema:
objectclasses: ( 2.5.6.6 NAME 'person' DESC 'Standard Person Object Class' SUP top
MUST (objectclass $ sn $ cn) MAY (description $ seeAlso $ telephoneNumber $ userPassword)
X-ORIGIN 'RFC 2252' )You can query and change the directory schema with standard LDAP operations because object classes are defined and directly stored in Directory Server.
Additional resources
3.3. Mapping the data to the default schema
You must map the data identified during the site survey to the existing default directory schema. If the elements in the schema do not match the existing default schema, you can create custom object classes and attributes.
The default directory schema is stored in the /usr/share/dirsrv/schema/ directory, containing all the common schema for the Directory Server. You can find the LDAPv3 standard user and organization schema in the 00core.ldif file. You can also find the configuration schema used by earlier versions of the directory in the 50ns-directory.ldif file.
Do not modify the default directory schema.
3.3.1. Data matched to schema elements
You can map the data identified in the site survey to the existing directory schema. This process involves the following steps:
- You must identify the type of object the data describes.
Sometimes, a piece of data can describe multiple objects. Determine if the difference needs to be noted in the directory schema. For example, a telephone number can describe an employee’s telephone number and a conference room’s telephone number. Determine if these different sorts of data need to be considered different objects in the directory schema.
- You must select a similar object class from the default schema. It is best to use the common object classes, such as groups, people, and organizations.
- You must select a similar attribute from the matching object class.
- You must identify the unmatched data from the site survey. If some pieces of data that do not match the object classes and attributes defined by the default directory schema, customize the schema.
The Directory Server Configuration, Command, and File Reference is useful for determining what attributes are available for your data. Each attribute is listed with object classes which accept it, and each object class is cross-listed with required and allowed attributes.
Additional resources
3.4. Customization of schema
You can extend the standard schema by using the web console in Directory Server by adding the attributes and object classes. You can also create an LDIF file and add schema elements manually.
The following rules are applicable while customizing the schema:
- You must keep the schema simple.
- You must reuse the schema elements.
- You must minimize the number of mandatory attributes defined for each object class.
- Do not define more than one object class or attribute for the same purpose (data).
- Do not modify any existing definitions of attributes or object classes.
You cannot delete or replace the standard schema when customizing the schema. Doing so can lead to compatibility problems with other directories or LDAP client applications.
Custom object classes and attributes are defined in the 99user.ldif file. Each instance maintains its own 99user.ldif file in the /etc/dirsrv/slapd-instance_name/schema/ directory. You can also create custom schema files and dynamically reload the schema into the server.
You can extend the schema when a given object class can not store specialized information about an organization, while the object classes and attributes supplied with the Directory Server should meet the most common corporate needs. You can also extend the schema to support the object classes and attributes required by an LDAP-enabled application’s unique data needs.
3.4.1. Assignment of object identifiers
You must assign a unique name and object identifier (OID) for each LDAP object class or attribute. When you define a schema,the elements require a base OID unique to your organization. Add another level of hierarchy to create new branches for attributes and object classes. Getting and assigning OIDs in schema involves the following steps:
-
Obtain an OID from the
Internet Assigned Numbers Authority(IANA) or a national organization. In some countries, corporations already have OIDs assigned to them. - Create an OID registry to track OID assignments. An OID registry is a list of the OIDs and descriptions of the OIDs used in the directory schema. This ensures that no OID is ever used for more than one purpose. Then publish the OID registry with the schema.
-
Create branches in the OID tree to accommodate schema elements. Create at least two branches under the OID branch or the directory schema, using OID.
1for attributes and OID.2for object classes. Add new branches as needed to define custom matching rules or controls (for example, OID.`3).
Additional resources
3.4.2. Strategies for defining new object classes
You can create new object classes in the following two ways:
- Create new object classes, one for each object class structure where you can add an attribute.
- Create a single object class that supports all the custom attributes created for the directory. You can create this object class by defining it as an auxiliary object class.
You can mix the two methods. For example, you want to create the attributes exampleDateOfBirth, examplePreferredOS, exampleBuildingFloor, and exampleVicePresident. A simple solution is to create several object classes that allow some subset of these attributes.
-
The
examplePersonobject class allowsexampleDateOfBirthandexamplePreferredOS. The parent ofexamplePersonisinetOrgPerson. -
The
exampleOrganizationobject class allowsexampleBuildingFloorandexampleVicePresident. The parent of exampleOrganization is theorganizationobject class.
The new object classes appear in LDAPv3 schema format as follows:
objectclasses: ( 2.16.840.1.117370.999.1.2.3 NAME 'examplePerson' DESC 'Example Person Object Class'
SUP inetorgPerson MAY (exampleDateOfBirth $ examplePreferredOS) )
objectclasses: ( 2.16.840.1.117370.999.1.2.4 NAME 'exampleOrganization' DESC 'Organization Object Class'
SUP organization MAY (exampleBuildingFloor $ exampleVicePresident) )Alternatively, you can create a single object class that allows all of these attributes and use it with any entry that needs them. The single object class appears as follows:
objectclasses: (2.16.840.1.117370.999.1.2.5 NAME 'exampleEntry' DESC 'Standard Entry Object Class' SUP top
AUXILIARY MAY (exampleDateOfBirth $ examplePreferredOS $ exampleBuildingFloor $ exampleVicePresident) )
The new exampleEntry object class is marked AUXILIARY which means that it can be used with any entry regardless of its structural object class.
You can organize new object class depending on the organization environment. Consider the following when you decide on the implementation of the new object classes:
- You must use a single object class if more than two or three object classes are added to the schema.
- Multiple object classes need a rigid data design. Rigid data design forces attention to the object class structure under which every piece of data is placed that can either be helpful or cumbersome.
-
You can use data by using single object classes when data can be applied to more than one type of object class, such as people and asset entries. For example, you can set a custom
preferredOSattribute on both a person and a group entry. A single object class can allow this attribute on both types of entries. -
You must avoid required attributes for new object classes. When you are specifying
requireinstead ofallowfor attributes in new object classes it can make the schema inflexible. After you define a new object class decide what attributes it allows and requires, and from what object classes it inherits attributes.
3.4.3. Strategies for defining new attributes
You must use standard attributes for both application compatibility and long-term maintenance. You must search the attributes already existing in the default directory schema and use them with a new object class or check the Directory Server schema guide. However, if the standard schema does not contain all the necessary information, add new attributes and new object classes.
For example, a person entry may need more attributes than the person, organizationalPerson, or inetOrgPerson object classes support by default. No attribute exists within the standard Directory Server schema to store birth dates. You can create and set a new attribute, dateOfBirth as an allowed attribute within a new auxiliary object class, examplePerson:
attributetypes: ( dateofbirth-oid NAME 'dateofbirth' DESC 'For employee birthdays'
SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 X-ORIGIN 'Example defined')
objectclasses: ( 2.16.840.1.117370.999.1.2.3 NAME 'examplePerson' DESC 'Example Person Object Class'
SUP inetorgPerson MAY (exampleDateOfBirth $ cn) X-ORIGIN 'Example defined')You cannot add or delete custom attributes to standard schema elements. If the directory requires custom attributes, add custom object classes to contain them.
3.4.4. Deletion of schema elements
You cannot delete the schema elements included by default in Directory Server. Unused schema elements represent no operational or administrative overhead. Deleting parts of the standard LDAP schema it can cause compatibility problems with future installations of Directory Server and other directory-enabled applications.
You can, however, delete the unused custom schema elements. Before removing the object class definitions from the schema, modify each entry using the object class. Removing the definition first might prevent the entries that use the object class from being modified later. The schema checks on modified entries also fails unless the unknown object class values are removed from the entry.
3.4.5. Creation of custom schema files
You can create custom schema files for the Directory Server to use it in addition to the 99user.ldif file provided with Directory Server. These schema files have new, custom attributes and object classes specific to the organization. The new schema files are located in the schema directory, /etc/dirsrv/slapd-instance_name/schema/. All standard attributes and object classes are loaded only after custom schema elements have been loaded.
Custom schema files can not be numerically or alphabetically higher than 99user.ldif.
After you create the custom schema files, the schema changes can be distributed among all servers in the following way:
-
You can manually copy these custom schema files to the instance’s schema directory
/etc/dirsrv/slapd-instance/schemaand load the schema, restart the server or reload the schema dynamically by running theschema-reload.plscript. -
You can modify the schema on the server with an LDAP client, such as the web console or by using
ldapmodifycommand. -
With replication, all of the replicated schema elements are copied into the consumer servers
99user.ldiffile. To keep the schema in a custom schema file, like90example_schema.ldif, the file has to be copied over to the consumer server manually. Replication does not copy schema files.
When you do not copy these custom schema files to all of the servers, the schema information is only replicated to the consumer server when changes are made to the schema on the supplier server. When the schema definitions are replicated to a consumer server where they do not already exist, they are stored in the 99user.ldif file.
The directory does not track where schema definitions are stored. You can store schema elements in the 99user.ldif file of consumers if the schema is maintained on the supplier server only.
3.4.6. Best practices for custom schema
Following suggestions help you to define a compatible and manageable custom schema.
Naming Schema Files
Name custom schema files numerically and alphabetically lower than 99user.ldif. The 99user.ldif file contains attributes with an X-ORIGIN value of 'user defined'. The Directory Server writes all 'user defined' schema elements to the highest named file, numerically then alphabetically. If a name of the schema file is 99zzz.ldif and the schema is updated, all attributes with an X-ORIGIN value of 'user defined' are written to the 99zzz.ldif file. As a result, both LDIF files that contain duplicate information, and some information in the 99zzz.ldif file might be erased.
When naming custom schema files, use the following naming format: [00-99]yourName.ldif.
Using 'user defined' as the origin
Do not use 'user defined' in the X-ORIGIN field of custom schema files, for example 60example.ldif, because 'user defined' is used internally by the Directory Server when a schema is added over LDAP.
If the custom schema elements are added directly to the 99user.ldif manually, use 'user defined' as the value of X-ORIGIN. If a different X-ORIGIN value is set, the server simply may overwrites it.
Using an X-ORIGIN of value 'user defined' prevents removing schema definitions in the 99user.ldif file by the Directory Server.
For example:
attributetypes: ( exampleContact-oid NAME 'exampleContact' DESC 'Example Corporate contact' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 X-ORIGIN 'Example defined')
After the Directory Server loads the schema entry, it appears as follows:
attributetypes: ( exampleContact-oid NAME 'exampleContact'
DESC 'Example Corporate contact'
SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
X-ORIGIN ('Example defined' 'user defined') )Defining Attributes before Object Classes
When you add new schema elements, define all attributes before they are used in an object class. Attributes and object classes can be defined in the same schema file.
Defining Schema in a Single File
Define each custom attribute or object class in one schema file to prevent the server from overriding any previous definitions when it loads the most recently created schema. The server loads the schema in numerical order first, then alphabetical order. Decide how to keep from having schema in duplicate files:
- Be careful with what schema elements are included in each schema file.
-
Be careful in naming and updating the schema files. When schema elements are edited through LDAP tools, the changes are automatically written alphabetically to the last file. Most schema changes, are written to the default
99user.ldiffile and not to the custom schema file, such as60example.ldif. The schema elements in99user.ldiffile override duplicate elements in other schema files. -
If you manage the schema by using the web console, add all the schema definitions to the
99user.ldiffile.
3.5. Consistent schema overview
The LDAP client applications locates directory entries by using a consistent schema in Directory Server. You cannot locate information in the directory tree by using an inconsistent schema because it uses different attributes or formats to store the same information.
You can maintain schema consistency in the following ways:
- You can use schema checking to ensure that attributes and object classes confirm to the schema rules.
- You can use syntax validation to ensure that attribute values match the required attribute syntax.
- You can select and apply a consistent data format.
3.5.1. Schema checking
Schema checking validates that all new or modified directory entries conform to the schema rules. By default, directory enables schema checking. When the rules are violated, the directory rejects the requested change.
Schema checking validates that the proper attributes are present. You can use syntax validation to verify that attribute values are in the correct syntax. Do not disable this feature.
When schema checking is enabled, you must pay attention to required and allowed attributes as defined by the object classes. The Directory Server can return an object class violation message when you add an attribute to an entry that is neither required nor allowed according to the entry’s object class definition.
For example, if an entry is defined to use the organizationalPerson object class, then the common name (cn) and surname (sn) attributes are required for the entry. The values for these attributes must be set when the entry is created. In addition, there is a long list of attributes that can optionally be used on the entry, including descriptive attributes like telephoneNumber, uid, streetAddress, and userPassword.
3.5.2. Overview of syntax validation
Syntax validation means the Directory Server validates that the value of an attribute matches the required syntax for that attribute. For example, syntax validation can confirm that a new telephoneNumber attribute has a valid telephone number for its value. It is enabled by default.
You can optionally configure additional settings for syntax validation to log warning messages about syntax violations and then either reject the modification or allow the modification process to succeed.
Syntax validation checks the LDAP operations if a new attribute value is added. It does not process existing attributes or attributes added through database operations like replication. Existing attributes can be validated using the dsconf schema validate-syntax command.
This feature validates all attribute syntaxes except the binary syntaxes and non-standard syntaxes, which do not have a defined required format. The syntaxes are validated against RFC 4514, except for DNs, which are validated against the less strict RFC 1779 or RFC 2253.
You can configure strict DN validation.
3.5.2.1. Syntax validation for directory server operations
Syntax validation is applicable for standard LDAP operations like creating entries (add) or editing attributes (modify). When you validate attribute syntax it can impact other Directory Server operations.
Database Encryption
You can encrypt an attribute before the value is written in the database for LDAP operations. This means that encryption is performed after the attribute syntax is validated. You can import and export encrypted database.
You must perform export and import operations with the flag --encrypted(dsctl), which allows syntax validation to occur for the import operation.
If you export the encrypted database without using the --encrypted flag (which is not supported), then an LDIF with encrypted values is created. You cannot validate the encrypted attributes, a warning is logged, and attribute validation is skipped in the imported entry when this LDIF is imported.
Synchronization
There can be differences in the allowed or enforced syntaxes for attributes in Windows Active Directory entries and Directory Server entries. You cannot sync the Active Directory values because syntax validation enforces the RFC standards in the Directory Server entries.
Replication
You can use syntax validation if the Directory Server 11.0 instance is a supplier which replicates its changes to a consumer. However, suppose the supplier in replication is an older version of the Directory Server or has syntax validation disabled. In that case, syntax validation can not be used on the 11.0 consumer because the Directory Server 11.0 consumer can reject attribute values that the supplier allows.
3.5.3. Consistent data formats
You can place data with attribute value by using LDAP schema. However, it is important to store data consistently in the directory tree by selecting a format appropriate for the LDAP client applications and directory users.
You can represent data in the data formats specified in RFC 2252 by using the LDAP protocol and Directory Server. For example, the correct LDAP format for telephone numbers is defined in two ITU-T recommendations documents:
-
ITU-T Recommendation E.123. Notation for national and international telephone numbers. -
ITU-T Recommendation E.163. Numbering plan for the international telephone services. For example, a US phone number is formatted as+1 555 222 1717.
As another example, the postalAddress attribute has an attribute value in the form of a multi-line string that uses dollar signs ($) as line delimiters. A properly formatted directory entry appears as follows:
postalAddress: 1206 Directory Drive$Pleasant View, MN$34200Attributes require strings, binary input, integers, and other formats. You can set the format in the schema definition for the attribute.
3.5.4. About maintaining consistency in replicated schema
The changes are recorded in the changelog when you edit the directory schema. During replication, the changelog is scanned for changes and if any changes are being replicated. Maintaining consistency in replicated schema allows replication to continue without any error.
Consider the following points for maintaining consistent schema in a replicated environment:
Do not modify the schema on a read-only replica.
When you modify the schema on a read-only replica, it introduces an inconsistency in the schema and causes replication to fail.
Do not create two attributes with the same name that use different syntaxes.
When you create an attribute in a read-write replica with the same name as an attribute on the supplier replica but with a different syntax from the attribute on the supplier, replication will fail.
