Sun Java System Directory Server Enterprise Edition 6.0 Administration Guide

About Custom Schema

You can extend the standard schema if it is too limited for your directory needs. Follow these guidelines when customizing schema:

Reuse existing schema elements whenever possible.
Minimize the number of mandatory attributes that 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.

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 and with LDAP client applications.

Do not modify any Directory Server internal operational attributes. You can, however, create your own operational variables for external applications.

Always define object classes instead of using objectClass: extensibleObject. Directory Server does not perform schema checking for entries that have the object class extensibleObject, so it does not constrain or check what attributes are present on the entry. Typos in applications, for example, giveName for the givenName attribute type, go unnoticed by Directory Server. Also, Directory Server must assume that all otherwise undefined attributes of extensibleObject entries are multivalued and have case-insensitive string syntax. Furthermore, some applications rely on entries having a particular object class. In general, if you have an application that requires an extension to an object class, do not relinquish schema management. Instead, create an auxiliary object class that contains the attributes that are required for the application.

This section contains information about the default directory schema, and about creating customized attributes and object classes.

Default Directory Server Schema

The schema provided with Directory Server is described in a set of files that are stored in the instance-path/config/schema/directory.

This directory contains all of the common schema for Directory Server and related products. The LDAP v3 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.

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 that is unique to your organization. One OID is enough to meet all of your schema needs. You then add new branches on that OID for your attributes and object classes.

Obtaining and assigning OIDs in your schema involves doing the following:

Obtaining 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, you can obtain an OID from IANA.
Creating an OID registry so you can track OID assignments.

An OID registry is a list that you maintain, which gives the OIDs and OID descriptions that are used in your directory schema. A OLD registry ensures that no OID is ever used for more than one purpose.
Creating 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, such as OID.3.

Naming Attributes and Object Classes

When creating names for new attributes and object classes, make the name meaningful so your schema is easier to use.

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 its custom schema elements. It might also add a special object class called ExamplePerson to identify Example.com employees in its directory.

Note that in LDAP, attribute type names and object class names are case insensitive. Applications should treat them as case insensitive strings.

When 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 approaches to creating new object classes:

Create many new object classes, one for each object class structure to which you want to add an attribute.
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.

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

Your new object classes would appear in LDAP v3 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. Then you can use the object class with any entry on which you want to use the 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.

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, if you plan to add more than two or three object classes to your schema, you might find it easier to use a single object class.
Multiple STRUCTURAL object classes require more careful and more rigid data design.

Rigid data design forces you to consider the object class structure on which every piece of data is placed. You might find this restriction 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 that you want preferredOS on both a person and a group entry. You might want to create only a single object class to allow this attribute.
Design object classes that 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 which attributes the object class allows and requires, and from which object class or classes it inherits.

When 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 those attributes in association with a new object class.

For example, you might 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. Allow this attribute to be used on entries that represent people by defining a new auxiliary class that allows this attribute.

When Creating Custom Schema Files

Keep 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 that you create should be defined in only one schema file. This practice prevents the server from overriding any previous definitions when the server loads the most recently created schema. Directory Server loads the schema files in numerical order first, then in alphabetical order.
When defining new schema definitions manually, best practice is generally 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 that you made in custom schema files might be overwritten. Using only the 99user.ldif file prevents possible duplications of schema elements and the danger of schema changes being overwritten.
As Directory Server loads schema files in alphanumeric order with numbers loaded first, you should name custom schema files as follows:
```
[00-99] filename.ldif
```
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 might encounter errors when loading the schema. In addition, all standard attributes and object classes are loaded only after your custom schema elements have been loaded.
Make sure that custom schema file names are not numerically or alphabetically higher than 99user.ldif because Directory Server uses the highest sequenced file for its internal schema management.

For example, if you created a schema file and named it 99zzz.ldif, the next time you update the schema, all of the attributes with an X-ORIGIN value of 'user defined' would be written to 99zzz.ldif. 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, identify the custom schema elements that 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 for other administrators to understand. For example X-ORIGIN ('user defined' 'Example.com Corporation defined').
  
  If you are adding schema elements manually and do not use 'user defined' in the X-ORIGIN field, the schema elements appear read-only in DSCC.
  
  The 'user defined' value is added automatically by the server if you add custom schema definitions by using LDAP or DSCC. However, if you do not add a more descriptive value in the X-ORIGIN field, you might later have difficulty understanding what the schema relates to.
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 timestamp of when the schema was changed. At the beginning of each replication session the server compares its timestamp with its consumer’s timestamp and, if necessary, pushes any schema changes. For custom schema files, the server maintains only one timestamp, which is associated with the 99user.ldif file. This means that any custom schema file changes or additions that 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.