Sun Java logo     Previous      Contents      Index      Next     

Sun logo
Sun Java(TM) System Directory Server 5.2 2005Q1 Deployment Planning Guide 

Chapter 3
Directory Server Schema

The site survey conducted in Chapter 2 provided information about the data you plan to store in your directory. Next, you must decide how to represent this data. The directory schema describes the types of data that can be stored in a directory. During schema design, each data element is mapped to an LDAP attribute, and related elements are gathered into LDAP object classes. Well-designed schema helps maintain data integrity.

This chapter describes how to design schema, and includes the following sections:

For more information about the object classes and attributes found in Directory Server, in addition to the schema files and directory configuration attributes, refer to the Directory Server Administration Reference. For information on replicating schema between servers, refer to Schema Replication.

Directory Server Schema

The directory schema maintains data integrity 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 the standard RFC LDAP schema, additional application-specific schema to support the features of the server, and Directory Server-specific schema extensions. While this schema meets most directory requirements, 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 for information on extending the schema.

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

The Directory Server schema supports not only the core LDAPv3 schema in RFC 2256, but many other popular product schemas as well. In addition to this, Directory Server 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 Sun for Directory Server's use, the X-ORIGIN field contains the value Sun ONE Directory Server.

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

objectclasses: ( 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, or OID, for the class (, the name of the object class (person), and a description of the class (Standard Person Object Class), then lists the required attributes (objectclass, sn, and cn) and the allowed attributes (description, seealso, telephoneNumber, and userPassword).

Like all Directory Server 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.

Schema Design Process

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

Where possible, it is best to use the 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 that it has been reviewed and agreed to by a large number of directory users.

Mapping Your Data to the Default Schema

The data you identified during your site survey, (see Performing a Site Survey) must be mapped to the default directory schema. This section describes how to view the default schema and provides a method for mapping your data to the appropriate schema elements.

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

Viewing the Default Directory Schema

The schema provided with Directory Server is described in a set of files stored in the following directory:


This directory contains all of the common schema for the Sun Java System products. The LDAPv3 standard user and organization schema is located in the 00core.ldif file. The configuration schema used by earlier versions of the directory is located in the 50ns-directory.ldif file.


Do not modify files in this directory while the server is running.

Any changes made manually will not be replicated until other changes are made by using either LDAP or the Directory Server Console.

Matching Data to Schema Elements

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

The following table maps directory schema elements to the data identified during the site survey:

Table 3-1 Data Mapped to Default Directory Schema



Object Class


Employee name




User password




Home phone number




Employee location




Office phone number




In Table 3-1, the employee name describes a person. The default directory schema contains 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, there is not 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 organizationalPerson object class, which in turn inherits from the person object class. The inetOrgPerson object's allowed attributes include 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 is too limited for your directory needs. Directory Server Console assists in managing the schema definition. For more information, refer to "Extending the Directory Schema" in the Directory Server Administration Guide.

Keep the following rules in mind when customizing schema:


Do not modify any Directory Server internal operational attributes, as these attributes may be modified or overwritten by Sun in future releases. You can however create your own operational variables for external applications.

Custom object classes and attributes are defined in the following file:


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

When to Extend Your Schema

While the object classes and attributes supplied with 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.

Obtaining 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. Obtaining and assigning OIDs in your schema involves the following steps:

Naming Attributes and Object Classes

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

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

Strategies for Defining New Object Classes

Add new object classes when the existing object classes do not support all of the information you need to store in a directory entry. There are two ways to create new object classes:

You may find it easiest to mix the two methods.

Suppose your site wants to create the attributes ExampleDepartmentNumber, and ExampleEmergencyPhoneNumber. 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 ExampleDepartmentNumber and ExampleEmergencyPhoneNumber. The parent of ExamplePerson would be inetOrgPerson. You might then create an object class called ExampleOrganization and have it also allow ExampleDepartmentNumber and ExampleEmergencyPhoneNumber. The parent of ExampleOrganization would be the organization object class.

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

objectclasses: ( NAME 'ExamplePerson'
 DESC 'Example Person Object Class' SUP inetorgPerson STRUCTURAL MAY
 (ExampleDepartmentNumber $ ExampleEmergencyPhoneNumber) )

objectclasses: ( NAME
 'ExampleOrganization' DESC 'Example Organization Object Class' SUP
 organization STRUCTURAL MAY (ExampleDepartmentNumber
 $ ExampleEmergencyPhoneNumber) )

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: ( NAME 'ExampleEntry'
 DESC 'Example Auxiliary Object Class' SUP top AUXILIARY MAY
 (ExampleDepartmentNumber $ ExampleEmergencyPhoneNumber) )

The new ExampleEntry object class is marked AUXILIARY, meaning that it can be used with any entry regardless of its structural object class.


The OID of the new object classes in the examples is based on the Sun Java System OID prefix and must not be used in the deployed product. To create your own new object classes, you must obtain your own OID. For more information, refer to Obtaining and Assigning Object Identifiers.

Consider the following when deciding how to implement new object classes:

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

Strategies for Defining New Attributes

Add new attributes when the existing attributes 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.

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 birth dates in your directory, no attribute exists within the standard Directory Server schema. You can create a new attribute called dateOfBirth and allow this attribute to be used on entries representing people by defining a new auxiliary class 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. If you delete parts of the standard LDAP schema you may run into compatibility problems with future installations of Directory Server and other directory-enabled applications.

If you extend the schema and find that you do not use the new elements, you can delete these unused elements. Before removing schema elements, make sure that no entry in the directory uses them. The easiest way to do this is to run an ldapsearch that returns all entries containing that schema element.

For example, before deleting the object class named myObjectClass, you would run the following ldapsearch command:

ldapsearch -h host -p port -s base "objectclass=myObjectClass"

If you find any such entries, you can delete them or the part that will be removed from the schema. If you remove the schema definition before removing the entries that use that definition, you might not be able to modify the entries afterwards. Schema checks on modified entries will also fail unless you remove the unknown values from the entry.

Creating Custom Schema Files - Best Practices and Pitfalls

You can create custom schema files other than the 99user.ldif file provided with Directory Server. However, you must bear the following in mind when creating custom schema files, especially when you are using replication:

For more information about replicating schema, see Schema Replication.

Maintaining Data Consistency

Maintaining data consistency within Directory Server assists LDAP client applications in locating directory entries. For each type of information you store in the directory, select the required object classes and attributes to support that information, and always use the same ones. If you use schema objects inconsistently, it becomes difficult to locate information efficiently.

You can maintain schema consistency in the following ways:

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

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.


Schema checking only checks that the proper attributes are present. It does not verify whether attribute values are in the correct syntax for the attribute. Directory Server includes an attribute called nsslapd-valuecheck which allows you to check attributes whose values have the DN syntax. However, this attribute is turned off by default, so no attribute values are checked.

By default, the directory enables schema checking. You should not turn schema checking off on a server that is accepting client updates. For information on turning schema checking on and off, refer to "Schema Checking" in the Directory Server Administration Guide.

With schema checking on, you must take note of the 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, 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.

When configuring schema checking, bear the following in mind:

Selecting Consistent Data Formats

LDAP schema allows you to place any data 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:

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 multiline 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

Consider the following points for maintaining consistent schema in a replicated environment:

For more information on schema replication, refer to Schema Replication.

Other Schema Resources

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

Previous      Contents      Index      Next     

Copyright 2005 Sun Microsystems, Inc. All rights reserved.