Previous      Contents      Index      Next
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:

Directory Server Schema
Schema Design Process
Mapping Your Data to the Default Schema
Customizing the Schema
Maintaining Data Consistency
Other Schema Resources

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: ( 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, or OID, for the class (2.5.6.6), 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:

Choosing predefined schema elements to meet as many of your needs as possible.
Extending the standard Directory Server schema to define new elements to meet your remaining needs.
Planning for schema maintenance.

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:

ServerRoot/slapd-serverID/config/schema

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.

Note	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:

Identify the type of object the data describes.

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 must be noted in your 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 must be considered as different objects in your schema.

Select a similar object class from the default schema.

Use the common object classes, such as groups, people, and organizations.

Select a similar attribute from the matching object class.

Select an attribute from within the matching object class that best matches the piece of data identified in your site survey.

Identify the unmatched data from 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 for more information.

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

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

Reuse existing schema elements whenever possible. For a complete list of the existing schema elements, refer to "Object Class Reference" and "Attribute Reference" in the Directory Server Administration Reference.
Minimize the number of mandatory attributes you define for each object class.
Do not define more than one object class or attribute for the same purpose.
Keep the schema as simple as possible.

Note	When customizing the schema, do not modify, delete, or replace any existing definitions of attributes or object classes in the standard schema. Doing so can lead to compatibility problems with other directories or other LDAP client applications.

Note	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:

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

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

When to Extend Your Schema
Obtaining and Assigning Object Identifiers
Naming Attributes and Object Classes
Strategies for Defining New Object Classes
Strategies for Defining New Attributes
Deleting Schema Elements
Creating Custom Schema Files - Best Practices and Pitfalls

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:

Obtain an OID for your organization from the Internet Assigned Numbers Authority (IANA) or a national organization.

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

Create an OID registry so you can track OID assignments.

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 used for more than one purpose. You should then publish your OID registry with your schema.

Create branches in the OID tree to accommodate schema elements.

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

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 can create many new object classes, one for each object class structure to which you want to add an attribute.
You can create a single object class that supports all of the attributes that you create for your directory. You create this kind of an object class by defining it to be an AUXILIARY object class.

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: ( 1.3.6.1.4.1.42.2.27.999.1.2.3 NAME 'ExamplePerson'
 DESC 'Example Person Object Class' SUP inetorgPerson STRUCTURAL MAY
 (ExampleDepartmentNumber $ ExampleEmergencyPhoneNumber) )

objectclasses: ( 1.3.6.1.4.1.42.2.27.999.1.2.4 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: (1.3.6.1.4.1.42.2.27.999.1.2.5 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.

Note	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:

Multiple STRUCTURAL object classes result in more schema elements to create and maintain.

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.

Multiple STRUCTURAL object classes require more careful and rigid data design.

Rigid data design forces you to consider the object class structure on which every piece of data will be placed. You may find this to be either helpful or cumbersome.

Single AUXILIARY object classes simplify data design when you have data that you want to put on more than one type of object class structure.

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.

Try to design object classes which relate to real objects and group elements that constitute sensible groupings.
Avoid required attributes for new object classes.

Requiring attributes can make your schema inflexible. When you create 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 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:

When adding new schema elements, all attributes must be defined before they can be used in an object class. You can define attributes and object classes in the same schema file.
Each custom attribute or object class you create should be defined in only one schema file. This prevents 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 in alphabetical order).
When defining new schema definitions manually it is best practice to add these definitions to the 99user.ldif file.

When you update schema elements using LDAP, the new elements are written automatically to the 99user.ldif file. As a result, any other schema definition changes you may have made in custom schema files may be overwritten. Using only the 99user.ldif file prevents possible duplications of schema elements and the danger of schema changes being overwritten.

Because Directory Server loads schema files in alpha-numerical order, (with numbers being loaded first), you should name custom schema files as follows:

[00-99]filename.ldif

where the number is higher than any directory standard schema already defined.

If you name your schema file with a number that is 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.

Make sure that custom schema filenames are not numerically or alphabetically higher than 99user.ldif as Directory Server uses the highest sequenced file (numerically, then alphabetically) for its internal schema management.

If you created a schema file and named it 99zzz.ldif for example, the next time you updated the schema using LDAP or Directory Server Console, all of the attributes with an X-ORIGIN value of 'user defined' (usually stored in the 99user.ldif file) would be written to 99zzz.ldif instead. The result would be two LDIF files that contain duplicate information, and some information in the 99zzz.ldif file might be erased.

As a general rule, you should identify the custom schema elements you are adding with the following two items:
'user defined' in the X-ORIGIN field of custom schema files,
a more descriptive label such as 'Example.com Corporation defined' in the X-ORIGIN field, so that the custom schema element is easy to understand for other administrators. For example X-ORIGIN ('user defined' 'Example.com Corporation defined').

If you are adding schema elements manually and you do not use 'user defined' in the X-ORIGIN field, the schema elements will appear in the read-only section of Directory Server Console and you will not be able to use the console to edit them.

The 'user defined' value is added automatically by the server if you add custom schema definitions using LDAP or Directory Server Console. However, if you do not add a more descriptive value in the X-ORIGIN field, you may have difficulty understanding what the schema relates to at a later date.

Propagate any custom schema files manually to all of your servers, because these changes are not replicated automatically.

When you change the directory schema, the server keeps a time-stamp of when the schema was changed. At the beginning of each replication session the server compares its time-stamp with its consumer's time-stamp and, if necessary, pushes any schema changes. For custom schema files the server maintains only one time-stamp, which is associated with the 99user.ldif file. This means that any custom schema file changes or additions you make to files other than 99user.ldif will not be replicated. Therefore, you must propagate custom schema files to all other servers to ensure that all schema information is present throughout the topology.

To propagate custom schema changes you can either:

Replicate the changes by running the schema_push.pl script, or
Manually copy these custom schema files to all of your servers.

Both methods require that each server is restarted. If you use the schema_push.pl script to replicate custom schema definitions, you must maintain your schema on one master only. When schema definitions are replicated to a consumer on which they do not already exist, they will be stored in the 99user.ldif file as opposed to the custom schema file in which you defined them. Storing schema elements in the 99user.ldif file of consumers does not create a problem as long as you ensure that you maintain your schema on one master server only.

If you copy your schema files manually, you must remember to copy the files each time changes are made. If you do not do this the changes may 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.

If you do not want custom schema elements to be replicated to other servers in the replication topology:
define the schema elements you do not want to replicate in a separate file,
do not identify these elements as 'user defined' in the X-ORIGIN field,
set the nsslapd-schema-repl-useronly attribute to on so that only schema labeled as 'user defined' in the X-ORIGIN field will be replicated.

Note	You must also set the nsslapd-schema-repl-useronly attribute to on when replicating to a 5.0 or 5.1 Directory Server.

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:

Use schema checking to ensure that attributes and object classes conform to the schema rules.
Select and apply a consistent data format.

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.

Note	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:

Generally, you replicate all required attributes for each entry as defined in the schema, to avoid schema violations. If you want to filter out certain required attributes using fractional replication, you must disable schema checking.
If schema checking is enabled with fractional replication, you may not be able to initialize the server off line (from an ldif file). This is because the server will not allow you to load the ldif file if required attributes are filtered out.
Turning schema checking off may improve performance.
If you have disabled schema checking on a fractional consumer replica, the whole server instance on which that fractional consumer replica resides will not enforce schema. As a result, you should avoid configuring supplier (read-write) replicas on the same server instance.
Because schema is pushed by suppliers in fractional replication configurations, the schema on the fractional consumer replica will be a copy of the master replica's schema. Therefore, it will not correspond to the fractional replication configuration being applied.

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:

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

Do not modify the schema on a consumer server.

If you modify the schema on a consumer server, it will be more recent than the schema on the master server. When the master sends replication updates to the consumer, you will probably observe a number of replication errors because the schema on the consumer cannot support the new data.

In a multi-master replication environment, only modify schema on a single master server.

If you modify the schema on two master servers, the master that was most recently updated will propagate its version of the schema to the consumer. This means that the schema on the consumer will be inconsistent with the schema on the other master.

Note	Directory Server 5.2 uses the 11rfc2307.ldif schema file. The schema file conforms to rfc2307: Versions of Directory Server prior to Directory Server 5.2 use the 10rfc2307.ldif schema file. If replication is enabled between servers running different schema files, replication fails. On the Directory Server instance that is using the 10rfc2307.ldif file, remove the 10rfc2307.ldif file and replace it with a copy of the 11rfc2307.ldif file.

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:

Internet Engineering Task Force (IETF)
http://www.ietf.org
Understanding and Deploying LDAP Directory Services
T. Howes, M. Smith, G. Good, Macmillan Technical Publishing, 1999.
RFC 2252: LDAPv3 Attribute Syntax Definitions
http://www.ietf.org/rfc/rfc2252.txt
RFC 2256: Summary of the X.500 User Schema for Use with LDAPv3
http://www.ietf.org/rfc/rfc2256.txt
RFC 2251: Lightweight Directory Access Protocol (v3)
http://www.ietf.org/rfc/rfc2251.txt

Previous      Contents      Index      Next

---

Copyright 2005 Sun Microsystems, Inc. All rights reserved.