Deployment Guide
Red Hat Directory Server                                                            
Previous
 Contents
 Index
 Next

Chapter 3

How to Design the Schema

The site survey you conducted in chapter 2, "How to Plan Your Directory Data," generated information about the data you plan to store in your directory. Next, you must decide how to represent the data you store. Your directory schema describes the types of data you can store in your directory. During schema design, you map each data element to an LDAP attribute and gather related elements into LDAP object classes. Well-designed schema help maintain the integrity of the data you store in your directory.

This chapter describes the directory schema and how to design schema for your unique needs. This chapter contains the following sections:

For information on replicating schema, refer to "Schema Replication," on page 135.

Schema Design Process Overview

During schema design, you select and define the object classes and attributes used to represent the entries stored by Red Hat Directory Server (Directory Server). Schema design involves the following steps:

It is best to use existing schema elements defined in the standard schema provided with Directory Server. Choosing standard schema elements helps ensure compatibility with directory-enabled applications. In addition, as the schema is based on the LDAP standard, you are assured it has been reviewed and agreed to by a wide number of directory users.

Standard Schema

Your directory schema maintain the integrity of the data stored in your directory by imposing constraints on the size, range, and format of data values. You decide what types of entries your directory contains (people, devices, organizations, and so forth) and the attributes available to each entry.

The predefined schema included with Directory Server contains both the standard LDAP schema as well as additional application-specific schema to support the features of the server. While this schema meets most directory needs, you may need to extend it with new object classes and attributes to accommodate the unique needs of your directory. Refer to "Customizing the Schema," on page 48, for information on extending the schema.

The following sections describe the format, standard attributes, and object classes included in the standard schema.

Schema Format

Directory Server bases its schema format on version 3 of the LDAP protocol (LDAPv3). This protocol requires directory servers to publish their schema through LDAP itself, allowing directory client applications to retrieve the schema programmatically and adapt their behavior based on it. The global set of schema for Directory Server can be found in the entry named cn=schema.

The Directory Server schema differs slightly from the LDAPv3 schema, as it uses its own proprietary object classes and attributes. In addition, it uses a private field in the schema entries called X-ORIGIN, which describes where the schema entry was defined originally. For example, if a schema entry is defined in the standard LDAPv3 schema, the X-ORIGIN field refers to RFC 2252. If the entry is defined by Red Hat for the Directory Server's use, the X-ORIGIN field contains the value Red Hat Directory Server.

For example, the standard person object class appears in the schema as follows: 

objectclasses: ( 2.5.6.6 NAME 'person' DESC 'Standard Person 
Object  Class' SUP top MUST (objectlass $ sn $ cn) MAY 
(description $  seealso $ telephoneNumber $ userPassword) 
X-ORIGIN 'RFC 2252' )

This schema entry states the object identifier, or OID, for the class (2.5.6.6), the name of the object class (person), a description of the class (standard person), then lists the required attributes (objectclass, sn, and cn) and the allowed attributes (description, seealso, telephoneNumber, and userPassword).

For more information about the LDAPv3 schema format, refer to the LDAPv3 Attribute Syntax Definitions document (RFC2252).

The differences between current Directory Server schema and Directory Server 4.x are described in the following table:

Directory Server 4.x Syntax    
Equivalent Current Directory Server Syntax
bin
Binary
ces
IA5String
cis
DirectoryString
dn
DN
int
INTEGER
tel
TelephoneNumber

In addition, current releases of Directory Server support the following syntaxes:

Syntax      
Description
OctetString
Same behavior as Binary.
URI
Same behavior as IA5String.
Boolean
Boolean values have a value of either "TRUE" or "FALSE."
GeneralizedTime    
Values in this syntax are encoded as printable strings. It is strongly recommended that GMT time be used. The time zone must be specified.
CountryString
A value in this syntax is encoded the same as a value of DirectoryString syntax. This syntax is limited to values of exactly two printable string characters.
PostalAddress
Values in this syntax are encoded according to the following:
postal-address = dstring *("$" dstring)
In the above, each dstring component of a postal address value is encoded as a value of type DirectoryString syntax. Backslashes and dollar characters, if they occur in the component, are quoted. Many servers limit the postal address to six lines of up to thirty characters. For example:
1234 Main St.$Anytown,TX 12345$USA

Standard Attributes

Attributes hold specific data elements such as a name or a fax number. Directory Server represents data as attribute-data pairs, a descriptive attribute associated with a specific piece of information. For example, the directory can store a piece of data such as a person's name in a pair with the standard attribute, in this case commonName (cn). So, an entry for a person named Babs Jensen has the following attribute-data pair: 

cn: Babs Jensen

In fact, the entire entry is represented as a series of attribute-data pairs. The entire entry for Babs Jensen might appear 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: [email protected]

The entry for Babs contains multiple values for some of the attributes. The attribute givenName appears twice, each time with a unique value. The object classes that appear in this example are explained in the next section, "Standard Object Classes."

In the schema, each attribute definition contains the following information:

For example, 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 )

Standard Object Classes

Object classes are used to group related information. Typically, an object class represents a real object, such as a person or a fax machine. Before you can use an object class and its attributes in your directory, it must be identified in the schema. Your directory recognizes a standard list of object classes by default. See the Red Hat Directory Server Schema Reference for more information.

Each directory entry belongs to one or more object classes. Once you place an object class identified in your schema on an entry, you are telling the Directory Server that the entry can have a certain set of attribute values and must have another, usually smaller, set of attribute values.

Object class definitions contain the following information:

For an example of a standard object class as it appears in the schema, refer to "Schema Format," on page 42.

As is the case for all of the Directory Server's schema, object classes are defined and stored directly in Directory Server. This means that you can both query and change your directory's schema with standard LDAP operations.

Mapping Your Data to the Default Schema

The data you identified during your site survey, as described in "Performing a Site Survey," on page 28, must be mapped to the existing directory default schema. This section describes how to view the existing default schema and provides a method for mapping your data to the appropriate existing schema elements.

If you find elements in your schema that do not match the existing default schema, you may need to create custom object classes and attributes. Refer to "Customizing the Schema," on page 48, for more information.

Viewing the Default Directory Schema

The default directory schema is stored here: 

serverRoot/slapd-serverID/config/schema

This directory contains all of the common schema for the Directory Server. The LDAPv3 standard user and organization schema can be found in the 00core.ldif file. The configuration schema used by earlier version of the directory can be found in the 50ns-directory.ldif file.

Note

You should not modify the default directory schema.


For more information about each object class and attribute found in directory, refer to the Red Hat Directory Server Schema Reference. For more information about the schema files and directory configuration attributes, refer to Red Hat Directory Server Configuration, Command, and File Reference.

Matching Data to Schema Elements

The data you identified in your site survey now needs to be mapped to the existing directory schema. This process involves the following steps:

Select an object that best matches the data described in your site survey. Sometimes, a piece of data can describe multiple objects. You need to determine if the difference needs to be noted in your directory schema. For example, a telephone number can describe an employee's telephone number and a conference room's telephone number. It is up to you to determine if these different sorts of data need to be considered different objects in your directory schema.
It is best to use the common object classes, such as groups, people, and organizations.
Select an attribute from within the matching object class that best matches the piece of data you identified in your site survey.
If there are some pieces of data that do not match the object classes and attributes defined by the default directory schema, you will need to customize the schema. See "Customizing the Schema," on page 48, for more information.

For example, the following table maps directory schema elements to the data identified during the site survey in chapter 2:

Table 3-1 Data Mapped to Default Directory Schema  
Data
Owner
Object Class
Attribute
Employee name
HR
person
cn (commonName)
User password
IS
person
userPassword
Home phone number
HR
inetOrgPerson
homePhone
Employee location
IS
inetOrgPerson
localityName
Office phone number  
Facilities  
person  
telephoneNumber

In the table, the employee name describes a person. In the default directory schema, we found the person object class, which inherits from the top object class. This object class allows several attributes, one of which is the cn or commonName attribute, which describes the full name of the person. This attribute makes the best match for containing the employee name data.

The user password also describes an aspect of the person object. In the list of allowed attributes for the person object, we find userPassword.

The home phone number describes an aspect of a person; however, we do not find an appropriate attribute in the list associated with the person object class. Analyzing the home phone number more specifically, we can say it describes an aspect of a person in an organization's enterprise network. This object corresponds to the inetOrgPerson object class in the directory schema. The inetOrgPerson object class inherits from the organizationPerson object class, which in turn inherits from the person object class. Among the inetOrgPerson object's allowed attributes, we locate the homePhone attribute, which is appropriate for containing the employee's home telephone number.

Customizing the Schema

You can extend the standard schema if it proves to be too limited for your directory needs. To help you extend your schema, the Directory Server includes a schema management tool. For more information, see Red Hat Directory Server Administrator's Guide.

Keep the following rules in mind when customizing your schema:

Note

When customizing the schema, you should never delete or replace the standard schema. Doing so can lead to compatibility problems with other directories or other LDAP client applications.


Your custom object classes and attributes are defined in the following file: 

serverRoot/slapd-serverID/config/schema/99user.ldif

The following sections describe customizing the directory schema in more detail:

When to Extend Your Schema

While the object classes and attributes supplied with the Directory Server should meet most of your needs, you may find that a given object class does not allow you to store specialized information about your organization. Also, you may need to extend your schema to support the object classes and attributes required by an LDAP-enabled application's unique data needs.

Getting and Assigning Object Identifiers

Each LDAP object class or attribute must be assigned a unique name and object identifier (OID). When you define a schema, you need an OID unique to your organization. One OID is enough to meet all of your schema needs. You simply add another level of hierarchy to create new branches for your attributes and object classes. Getting and assigning OIDs in your schema involves the following steps:

In some countries, corporations already have OIDs assigned to them. If your organization does not already have an OID, one can be obtained from IANA. For more information, go to the IANA website at http://www.iana.org/cgi-bin/enterprise.pl.
An OID registry is a list you maintain that gives the OIDs and descriptions of the OIDs used in your directory schema. This ensures that no OID is ever use for more than one purpose. You should then publish your OID registry with your schema.
Create at least two branches under the OID branch or your directory schema, using OID.1 for attributes and OID.2 for object classes. If you want to define your own matching rules or controls, you can add new branches as needed (OID.3, for example).

Naming Attributes and Object Classes

When creating names for new attributes and object classes, make the names as meaningful as possible. This makes your schema easier to use for Directory Server administrators.

Avoid naming collisions between your schema elements and existing schema elements by including a unique prefix on all of your elements. For example, example.com Corporation might add the prefix example before each of their custom schema elements. They might add a special object class called examplePerson to identify example.com employees in their directory.

Strategies for Defining New Object Classes

There are two ways you can create new object classes:

You may find it easiest to mix the two methods.

For example, suppose your site wants to create the attributes exampleDateOfBirth, examplePreferredOS, exampleBuildingFloor, and exampleVicePresident. You can create several object classes that allow some subset of these attributes. You might create an object class called examplePerson and have it allow exampleDateOfBirth and examplePreferredOS. The parent of examplePerson would be inetOrgPerson. You might then create an object class called exampleOrganization and have it allow exampleBuildingFloor and exampleVicePresident. The parent of exampleOrganization would be the organization object class.

Your new object classes would appear in LDAPv3 schema format as follows: 

objectclasses: ( 2.16.840.1.17370.999.1.2.3 NAME 'examplePerson' 
 DESC 'Example Person Object Class' SUP inetorgPerson MAY 
(exampleDateOfBirth  $ examplePreferredOS) )
 
objectclasses: ( 2.16.840.1.17370.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 on which you want to use these attributes. The single object class would appear as follows: 

objectclasses: (2.16.840.1.17370.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, meaning that it can be used with any entry regardless of its structural object class.

Note

The OID of the new object classes in the example is based on the Red Hat OID prefix. To create your own new object classes, you must get your own OID. For more information, refer to "Getting and Assigning Object Identifiers," on page 49.


Choose the strategy for defining new object classes that works for you. Consider the following when deciding how to implement new object classes:

Generally, the number of elements remains small and needs little maintenance. However, you may find it easier to use a single object class if you plan to add more than two or three object classes to your schema.
Rigid data design forces you to consider the object class structure under which every piece of data will be placed. Depending on your personal preferences, you will find this to be either helpful or cumbersome.
For example, suppose you want preferredOS on both a person and a group entry. You may want to create only a single object class to allow this attribute.
Requiring attributes can make your schema inflexible. When creating a new object class, allow rather than require attributes.

After defining a new object class, you need to decide what attributes it allows and requires and from what object class(es) it inherits.

Strategies for Defining New Attributes

Add new attributes and new object classes when the existing object classes do not support all of the information you need to store in a directory entry.

Try to use standard attributes whenever possible. Search the attributes that already exist in the default directory schema and use them in association with a new object class. Create a new attribute if you cannot find a match in the default directory schema.

For example, you may find that you want to store more information on a person entry than the person, organizationalPerson, or inetOrgPerson object classes support. If you want to store the birth dates in your directory, no attribute exists within the standard Directory Server schema. You can choose to create a new attribute called dateOfBirth and allow this attribute to be used on entries representing people by defining a new auxiliary class, examplePerson, which allows this attribute.

Deleting Schema Elements

Do not delete the schema elements shipped with Directory Server. Unused schema elements represent no operational or administrative overhead. By deleting parts of the standard LDAP schema, you may run into compatibility problems with future installations of Directory Server and other directory-enabled applications.

However, if you extend the schema and find you do not use the new elements, feel free to delete the elements you don't use. Before removing the object class definitions from the schema, you need to modify each entry using the object class. Otherwise, if you remove the definition first, you might not be able to modify the entries that use the object class afterwards. Schema checks on modified entries will also fail unless you remove the unknown object class values from the entry.

Creating Custom Schema Files

You can create custom schema files other than the 99user.ldif file provided with Directory Server. However, your custom schema files should not be numerically or alphabetically higher than 99user.ldif or the server could experience problems.

The 99user.ldif file contains attributes with the an X-ORIGIN of 'user defined'. If you create a schema file called 99zzz.ldif, the next time you update the schema using LDAP or the Directory Server Console, all of the attributes with an X-ORIGIN value of 'user defined'will be written to 99zzz.ldif. The directory writes them to 99zzz.ldif because the directory uses the highest sequenced file (numerically, then alphabetically) for its internal schema management. The result is two LDIF files that contain duplicate information, and some information in the 99zzz.ldif file might be erased.

When naming custom schema files, name them as follows: 

[00-99]yourname.ldif

The directory loads these schema files in numerical order, followed by alphabetical order. For this reason, you should use a number scheme that is higher than any directory standard schema defined. For example, example.com Corporation creates a new schema file named 60examplecorp.ldif. If you name your schema file something lower than the standard schema files, the server may encounter errors when loading the schema. In addition, all standard attributes and object classes will be loaded only after your custom schema elements have been loaded.

You should not use 'user defined' in the X-ORIGIN field of your custom schema files as 'user defined' is used internally by the directory when schema is added over LDAP. Use something more descriptive, such as 'example.com Corporation defined'.

After you have created custom schema files, you can either:

If you do not copy these custom schema files to all of your servers, the schema information will only be replicated to the consumer when changes are made to the schema on the supplier using LDAP or the Directory Server Console.

When the schema definitions are then replicated to a consumer server where they do not already exist, they will be stored in the 99user.ldif file. The directory does not track where schema definitions are stored. Storing schema elements in the 99user.ldif file of consumers does not create a problem as long as you maintain your schema on the supplier server only.

If you copy your custom schema files to each server, changes to the schema files must be copied again to each server. If you do not copy them again, it is possible the changes will be replicated and stored in the 99user.ldif file on the consumer. Having the changes in the 99user.ldif file may make schema management difficult, as some attributes will appear in two separate schema files on a consumer, once in the original custom schema file you copied from the supplier and again in the 99user.ldif file after replication.

For more information about replicating schema, see "Schema Replication," on page 135.

Custom Schema Best Practices

Consider the following points when creating custom schema elements:

If you define custom schema files, for example, 60examplecorp.ldif, and then update these schema elements using LDAP, the new definitions will be written to the 99user.ldif file and not to your custom schema file, thus overriding your original custom schema definition. For example, changes to 60examplecorp.ldif will be overwritten by the definitions stored in 99user.ldif.
Using an X-ORIGIN of value 'user defined' ensures that schema definitions in the 99user.ldif file are not removed from the file by the directory. The directory does not remove them because it relies on an X-ORIGIN of 'user defined' to tell it what elements should reside in the 99user.ldif file.
For example, you create a schema entry manually in 99user.ldif 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')
After the directory 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') )

Maintaining Consistent Schema

A consistent schema within Directory Server aids LDAP client applications in locating directory entries. If you use an inconsistent schema, then it becomes very difficult to locate information in your directory tree efficiently.

Inconsistent schema use different attributes or formats to store the same information. You can maintain schema consistency in the following ways:

The following sections describe in detail how to maintain consistency within your schema.

Schema Checking

Schema checking ensures that all new or modified directory entries conform to the schema rules. When the rules are violated, the directory rejects the requested change.

Note

Schema checking checks only that the proper attributes are present. It does not verify whether attribute values are in the correct syntax for the attribute.


By default, the directory enables schema checking. We do not recommend turning it off. For information on turning schema checking on and off, see the Red Hat Directory Server Administrator's Guide.

With schema checking on, you must be attentive to required and allowed attributes as defined by the object classes. Object class definitions usually contain at least one required attribute and one or more optional attributes. Optional attributes are attributes that you are allowed, but not required, to add to the directory entry. If you attempt to add an attribute to an entry that is neither required nor allowed according to the entry's object class definition, then Directory Server returns an object class violation message.

For example, if you define an entry to use the organizationalPerson object class, then the commonName (cn) and surname (sn) attributes are required for the entry (you must specify values for these attributes when you create the entry). In addition, there is a fairly long list of attributes that you can optionally use on the entry. This list includes such descriptive attributes as telephoneNumber, uid, streetAddress, and userPassword.

Selecting Consistent Data Formats

LDAP schema allow you to place any data that you want on any attribute value. However, it is important to store data consistently in your directory tree by selecting a format appropriate for your LDAP client applications and directory users.

With the LDAP protocol and Directory Server, you must represent data in the data formats specified in RFC 2252.

In addition, the correct LDAP format for telephone numbers is defined in the following ITU-T Recommendations documents:

Notation for national and international telephone numbers.
Numbering plan for the international telephone services.

For example, a US phone number would be formatted as follows: 

+1 555 222 1717

The postalAddress attribute expects 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$34200

Maintaining Consistency in Replicated Schema

When you make changes to your directory schema, the change is recorded in the changelog. During replication, the changelog is scanned for changes, and any changes made are replicated. Maintaining consistency in replicated schema allows replication to continue smoothly. Consider the following points for maintaining consistent schema in a replicated environment:

Modifying the schema on a read-only replica introduces an inconsistency in your schema and causes replication to fail.
If you create an attribute in a read-write replica that has the same name as an attribute on the supplier replica but has a different syntax from the attribute on the supplier, replication will fail.

Other Schema Resources

Refer to the following links for more information about standard LDAPv3 schema:




Previous
 Contents
 Index
 Next
© 2001 Sun Microsystems, Inc. Used by permission. © 2005 Red Hat, Inc. All rights reserved.
Read the Full Copyright and Third-Party Acknowledgments.

 last updated May 20, 2005