Chapter 9   Extending the Directory Schema

Sun ONE Directory Server comes with a standard schema that includes hundreds of object classes and attributes. While the standard object classes and attributes should meet most of your requirements, you may need to extend your schema by creating new object classes and attributes.

This chapter describes how to extend your schema in the following sections:

• Schema Checking
• Overview of Extending the Schema
• Managing Attribute Definitions
• Managing Object Class Definitions
• Replicating Schema Definitions

Schema Checking

---

When schema checking is on, the Directory Server ensures that all import, add, and modify operations conform to the currently defined directory schema:

• The object classes and attributes of each entry conform to the schema.
• The entry contains all required attributes for all of its defined object classes.
• The entry contains only attributes that are allowed by its object classes.




---

Note	When modifying an entry, Directory Server performs schema checking on the entire entry, not only the attributes being modified. Therefore, the operation may fail if any object class or attribute in the entry does not conform to the schema.

---

Schema checking is turned on by default in the Directory Server, and you should always run the Directory Server with schema checking turned on. Many client applications assume that having schema checking turned on is an indication that all entries conform to the schema.

However, turning on schema checking will not verify the existing contents in the directory. The only way to guarantee that all directory contents conform to the schema is to turn on schema checking before adding any entries or before reinitializing all entries.

The only case where you might want to turn schema checking off is to accelerate import operations of LDIF files known to conform to the schema. However, there is a always risk of importing entries that do not conform to the schema, and this cannot be detected.

When an entry does not conform to the schema, it is impossible to search for this entry, and modification operations on it will fail. To make an entry comply with the schema you must do the following:

1. If your server is in a production environment, you may want to first make the entire server read-only to prevent any modifications while schema checking is turned off. See "Setting Global Read-Only Mode".
2. Turn off schema checking as described below.
3. Retrieve the entry and manually compare it with the currently defined schema to determine why it does not comply. See "Viewing Attributes" and "Viewing Object Classes".
4. Modify the entry to make it comply with the schema.

If you have many nonconforming entries, and these entries represent a pattern or new format for your data, you may consider modifying the schema instead. However, you should plan your schema ahead of your deployment to minimize changes to the schema. For more information, see Chapter 3, "Designing the Schema," in the Sun ONE Directory Server Deployment Guide.

5. Turn on schema checking as described below.
6. Unset the global read-only mode if you had enabled it.

Setting Schema Checking Using the Console

1. On the top-level Configuration tab of the Directory Server console, select the schema node in the configuration tree.

The right-hand panel contains the definition of the schema.

2. The status message at the top of the panel indicates whether schema checking is currently enabled or disabled. Click the button to the right to toggle schema checking off or on:

• The button is labeled Disable to turn off schema checking.
• The button will be labeled Enable when you can turn on schema checking.

The new schema checking policy is effective immediately.

Setting Schema Checking From the Command Line

You can also turn schema checking on and off by setting the nsslapd-schemacheck attribute of the cn=config entry:

ldapmodify -h host -p port -D "cn=Directory Manager" -w password
dn: cn=config
changetype: modify
replace: nsslapd-schemacheck
nsslapd-schemacheck: on or off

The server will enforce the new schema checking policy immediately.

Overview of Extending the Schema

---

When you add new attributes to your schema, you must create a new object class to contain them. Although it may seem convenient to just add the attributes you need to an existing object class that already contains most of the attributes you require, doing so compromises interoperability with LDAP clients.

Interoperability of Directory Server with existing LDAP clients relies on the standard LDAP schema. If you change the standard schema, you will also have difficulties when upgrading your server. For the same reasons, you cannot delete standard schema elements.

For more information on object classes, attributes, and the directory schema as well as guidelines for extending your schema, refer to Chapter 3, "Designing the Schema," in the Sun ONE Directory Server Deployment Guide. For information on standard attributes and object classes, see Part 4, "Directory Server Schema," in the Sun ONE Directory Server Reference Manual.

Directory Server schema is stored in attributes of the cn=schema entry of the directory. Like the configuration entry, this is an LDAP view of the schema that is read from files during server startup. The schema files are LDIF files located in:

ServerRoot/slapd-serverID/config/schema

This directory contains files for the standard schema used by Directory Server and other Sun ONE servers that rely on Directory Server. These files are described in "Schema Supported by Directory Server 5.2" in Chapter 9 of the Sun ONE Directory Server Reference Manual. The standard schema itself is described in Chapter 10, "Object Class Reference," and Chapter 11, "Attribute Reference" of the Sun ONE Directory Server Reference Manual.

Modifying the Schema Files

The schema files are read only once at startup by the server. The LDIF contents of the files are added to the in-memory LDAP view of the schema in cn=schema. Because the order of schema definitions is important, schema filenames are prefixed by a number and loaded in alphanumerical order. Schema files in this directory are writable only by the system user defined during installation.

To modify the schema definition in the files, you must create or modify the desired file and then restart the server. The syntax of definitions in the schema files is described in RFC 2252 (http://www.ietf.org/rfc/rfc2252.txt).

When defining the schema directly in an LDIF file, you must not use the value 'user defined' for the X-ORIGIN field. This value is reserved for schema elements that are defined through the LDAP view of cn=schema and that appear in 99user.ldif.

The file 99user.ldif contains additional ACIs for the cn=schema entry and all schema definitions added from the command-line or using the console. The file 99user.ldif will be overwritten when new schema definitions are added. If you wish to modify this file, you must restart the server immediately to ensure your changes will be permanent.

You should not modify the standard schema defined in the other schema files. However, you may add new files to define new attributes and object classes. For example, to define new schema elements in many servers, you could define them in a file named 98mySchema.ldif and copy this file to the schema directory of all servers. You must then restart all servers to load your new schema file.

Modifying the Schema From the Command Line

Because the schema is defined by the LDAP view in cn=schema, you may view and modify the schema online using the ldapsearch and ldapmodify utilities. However, you may modify only schema elements that have the value 'user defined' for the X-ORIGIN field. The server will refuse any modification to the other definitions.

Use ldapmodify to add and delete individual values of the attributeTypes and objectClasses attributes. To modify one of the values, you must delete the specific value and then add it as a new value because these attributes are multivalued (see "Modifying One Value of a Multi-Valued Attribute"). You must use the syntax for defining schema elements that is described in RFC 2252 (http://www.ietf.org/rfc/rfc2252.txt).

Any new element definitions and changes you make to user-defined elements will be saved in the file 99user.ldif.

Modifying schema definitions from the command line is prone to error because of the long values you must enter exactly. However, you may use this functionality in scripts that need to update your directory schema.

Modifying the Schema Using the Console

The recommended method for customizing your directory schema is to use the Directory Server console interface described in the following sections. The console lets you view the standard schema, and provides a graphical interface for defining new attributes and object classes and editing the elements you have defined.

Again, any new element definitions and changes you make to user-defined elements will be saved in the file 99user.ldif.

To extend the directory schema you should proceed in the following order:

1. Create the new attributes first, as described in "Creating Attributes".
2. Then create an object class to contain the new attributes and add the attributes to the object class. See "Creating Object Classes" for information.

Managing Attribute Definitions

---

The Directory Server console provides an interface to view all attributes in your schema and to can create, edit, and delete your own attribute definitions.

Viewing Attributes

To view information about all attributes that currently exist in your directory schema:

1. On the top-level Configuration tab of the Directory Server console, select the Schema node in the configuration tree, then select the Attributes tab in the right-hand panel.

This tab contains tables that list all the standard (read-only) and user-defined attributes in the schema. Holding the mouse over a line of a table will display the description string for the corresponding attribute.

The following tables describe the fields of the attribute tables.

Table 9-1    Columns of Tables in the Attributes Tab 

Column Heading	Description
Name	The name, sometimes called the type, of the attribute.
OID	The object identifier of the attribute. An OID is a string, usually of dotted decimal numbers, that uniquely identifies the schema object. For more information about OIDs, or to request a prefix for your enterprise, send mail to the IANA (Internet Assigned Number Authority) at iana@iana.org or visit the IANA website at http://www.iana.org/.
Syntax	The syntax describes the allowed format of values for this attribute the possible syntaxes are listed in Table 9-2.
Multivalued	The checkbox in this column designates whether or not the attribute is multivalued. A multivalued attribute may appear any number of times in an entry, but a single valued attribute may only appear once.

Table 9-2    Attribute Syntax Definitions 

Syntax Name	Definition
Binary (formerly bin)	Indicates that values for this attribute are treated as binary data.
Boolean	Indicates that this attribute has one of only two values: True or False.
Country String	Indicates that values for this attribute are limited to a two-letter country code specified by ISO 3166, for example FR.
DN (formerly dn)	Indicates that values for this attribute are DNs (distinguished names).
DirectoryString (formerly cis)	Indicates that values for this attribute may contain any UTF-8 encoded character and are not treated as case-sensitive.
GeneralizedTime	Indicates that values for this attribute are encoded as printable strings. The time zone must be specified. It is strongly recommended to use GMT.
IA5String (formerly ces)	Indicates that values for this attribute may contain only a subset of the ASCII characters and are treated as case-sensitive.
Integer (formerly int)	Indicates that valid values for this attribute are numbers.
OctetString	Same behavior as binary.
Postal Address	Indicates that values for this attribute are encoded as dstring[$ dstring]* where each dstring component is encoded as a value with DirectoryString syntax. Backslashes and dollar characters within dstring must be quoted, so that they will not be mistaken for line delimiters. Many servers limit the postal address to 6 lines of up to thirty characters. For example: 1234 Main St.$Anytown, CA 12345$USA
TelephoneNumber (formerly tel)	Indicates that values for this attribute are in the form of telephone numbers. It is recommended to use telephone numbers in international form.
URI	Indicates that the values for this attribute contain a URL, with an optional prefix such as http://, https://, ftp://, ldap://, or ldaps://. The URI values have the same behavior as IA5String (see RFC 2396, http://www.ietf.org/rfc/rfc2396.txt).

Creating Attributes

To add your own definition of an attribute to the schema:

1. On the top-level Configuration tab of the Directory Server console, select the Schema node in the configuration tree, then select the Attributes tab in the right-hand panel.
2. Click Create to display the Create Attribute dialog.
3. Enter the following information in the text fields to define your new attribute. Only the attribute name and syntax are required:

• Attribute Name - Enter a unique name for the attribute, also called its attribute type. Attribute names must begin with a letter and only contain ASCII letters, digits, and hyphens.




---

Note	The attribute name may contain upper-case letters, but no LDAP client should rely on them. Attribute names must be handled in a case-insensitive manner according to section 4.1.4 of RFC 2251 (http://www.ietf.org/rfc/rfc2251.txt).

---



• Attribute OID (optional) - Enter an object identifier for your attribute. OIDs are described in Table 9-1. If you do not specify an OID, the Directory Server automatically uses attributeName-oid. Note that for strict LDAP v3 compliance, you must provide a valid, numeric OID.
• Attribute aliases (optional) - Enter alternate names for your attribute in a comma-separated list.
• Attribute description (optional) - Enter a short descriptive text to explain the attribute's purpose.
• Syntax - Select a syntax from the drop-down list that describes the data to be held by the attribute. Available syntaxes are described in Table 9-2.
• Multi-valued - By default, attributes will be multi-valued. Deselect this checkbox if your attribute must have at most one value per entry.

4. Click OK in the Create Attribute dialog to define your new attribute. It will appear in the table of user-defined attributes.

Before defining values for this attribute in directory entries, you must create or edit an object class that requires or allows it, as described in "Managing Object Class Definitions".

Editing Attributes

You can edit only the user-defined attributes using the console. Before modifying the name, syntax, multi-valued definition of an attribute, you must ensure that no entry in the directory currently uses this attribute, otherwise clients will be unable to access that entry.

To modify the schema definition of an attribute:

1. On the top-level Configuration tab of the Directory Server console, select the Schema node in the configuration tree, then select the Attributes tab in the right-hand panel.
2. Select the attribute that you want to edit in the table of User Defined Attributes and click Edit.
3. Modify the fields of the Edit Attribute dialog to redefine your attribute.

If the OID string is based on the attribute's name, you should change the OID whenever you change the name. OIDs are described in Table 9-1. Available syntaxes are described in Table 9-2.

4. When you have finished editing the attribute, click OK to save your changes.

Deleting Attributes

You can delete only the user-defined attributes using the console. Before deleting an attribute definition, you must ensure that no entry in directory currently uses this attribute, otherwise clients will be unable to access that entry.

To delete the schema definition of an attribute:

1. On the top-level Configuration tab of the Directory Server console, select the Schema node in the configuration tree, then select the Attributes tab in the right-hand panel.
2. In the table of user-defined attributes, select the attribute and click Delete.
3. Confirm the delete when prompted.

The server will delete the attribute definition immediately. There is no undo.

Managing Object Class Definitions

---

The Directory Server console also provides an interface to view all object classes in your schema and to can create, edit, and delete your own object class definitions.

Viewing Object Classes

To view information about all object classes that are currently defined in your directory schema:

1. On the top-level Configuration tab of the Directory Server console, select the Schema node in the configuration tree, then select the Object Classes tab in the right-hand panel.

This tab contains lists of all the standard (read-only) and user-defined object classes in the schema.

2. Select the object class that you want to view from either list.

The other fields in the tab display the following information about the selected object class:

Table 9-3    Fields of the Object Classes Tab 

Field	Description
Required Attributes	Contains a list of attributes that must be present in entries that use this object class. This list includes inherited attributes.
Allowed Attributes	Contains a list of attributes that may be present in entries that use this object class. This list includes inherited attributes.
Parent	The parent identifies the object class from which an object class inherits its attributes and structure. Object classes automatically inherit the required and allowed attributes from their parent object class.
OID	The object identifier of the object class. An OID is a string, usually of dotted decimal numbers, that uniquely identifies the schema object. For more information about OIDs, or to request a prefix for your enterprise, send mail to the IANA (Internet Assigned Number Authority) at iana@iana.org or visit the IANA website at http://www.iana.org/.

Creating Object Classes

If you are creating several object classes that inherit from one another, you must create the parent object classes first. If your new object class will use custom attributes, you must also define those first.

---

Note	The console only allows you to create structural object classes. These object classes must inherit from a parent. To define auxiliary and abstract object classes, you must use the command line utilities.

---

To add your own definition of an object class to the schema:

1. On the top-level Configuration tab of the Directory Server console, select the Schema node in the configuration tree, then select the Object Classes tab in the right-hand panel.
2. Click Create to display the Create Object Class dialog.
3. Enter the following information in the text fields to define your new object class:

• Name - Enter a unique name for the object class.
• Parent - Select an existing object class to be the parent. By default, top is selected and must be used if your object class does not inherit from any other. The required and allowed attributes inherited from the parent and its parents are shown in the corresponding lists.

Typically, if you want to add new attributes for user entries, the parent would be the inetOrgPerson object class. If you want to add new attributes for corporate entries, the parent is usually organization or organizationalUnit. If you want to add new attributes for group entries, the parent is usually groupOfNames or groupOfUniqueNames.

• OID (Optional) - Enter an object identifier for your attribute. OIDs are described in Table 9-3. If you do not specify an OID, the Directory Server automatically uses objectClassName-oid. Note that for strict LDAP v3 compliance, you must provide a valid, numeric OID.

4. Define the attributes that entries using your new object class will contain:

• To define attributes that must be present, select one or more of them in the Available Attributes list and then click the Add button to the left of the Required Attributes box.
• To define attribute that may be present, select one or more of them in the Available Attributes list and then click the Add button to the left of the Allowed Attributes box.
• To remove an attribute that you previously added, highlight the attribute in either list and then click the corresponding Remove button. You cannot remove allowed or required attributes that are inherited from the parent object class.

5. Click OK in the Create Object Class dialog to define your new object class. It will appear in the table of user-defined object classes, and you may now define entries with this object class.

Editing Object Classes

You can edit only the user-defined object classes using the console. Before modifying the definition of an object class, you must ensure that no entry in the directory currently uses it, otherwise clients will be unable to access that entry.

To modify the schema definition of an object class:

1. On the top-level Configuration tab of the Directory Server console, select the Schema node in the configuration tree, then select the Object Class tab in the right-hand panel.
2. Select the object class that you want to edit in the list of User Defined Object Classes and click Edit.
3. Modify the fields of the Edit Object Class dialog to redefine your object class.

You cannot rename the object class nor change its OID. To modify these, delete the object class and create a new one.

• Parent - Select an existing object class to be the parent. The required and allowed attributes inherited from the parent and its parents are shown in the corresponding lists.
• To define attributes that must be present, select one or more of them in the Available Attributes list and then click the Add button to the left of the Required Attributes box.
• To define attribute that may be present, select one or more of them in the Available Attributes list and then click the Add button to the left of the Allowed Attributes box.
• To remove an attribute that you previously added, highlight the attribute in either list and then click the corresponding Remove button. You cannot remove allowed or required attributes that are inherited from the parent object class.

4. When you have finished editing the object class, click OK to save your changes.

Deleting Object Classes

You can delete only the user-defined object classes using the console. Before deleting an object class definition, you must ensure that no entry in directory currently uses this object class, otherwise clients will be unable to access that entry.

To delete the schema definition of an object class:

1. On the top-level Configuration tab of the Directory Server console, select the Schema node in the configuration tree, then select the Object Class tab in the right-hand panel.
2. In the list of user-defined object classes, select the object class name and click Delete.
3. Confirm the delete when prompted.

The server will delete the object class definition immediately. There is no undo.

Replicating Schema Definitions

---

Whenever you configure the replication of one or more suffixes between two servers, the schema is automatically replicated as well. This ensures that all replicas have a complete, identical schema that defines all object classes and attributes that may be replicated to the consumers. Therefore, master servers also contain the master schema.

To enforce the schema on all replicas, you must enable schema checking on all masters. Because the schema is checked on the master where the LDAP operation is performed, it does not need to be checked when updating the consumer. To improve performance, the replication mechanism bypasses schema checking on consumer replicas.

---

Note	You should not turn off schema checking on hubs and dedicated consumers. Schema checking has no performance impact on a consumer, and it should be left on to indicate that the replica contents conform to its schema.

---

Master servers replicate the schema automatically to their consumers during consumer initialization and anytime the schema is modified through the console or through the command-line tools. By default, the entire schema is replicated and any additional schema elements that do not yet exist on the consumer will be created there and stored in the 99user.ldif file.

For example, assume a master server contains schema definitions in the 98mySchema.ldif file when it is started, and you then define replication agreements to other servers, either masters, hubs, or dedicated consumers. When you subsequently initialize the replicas from this master, the replicated schemas will contain the definitions from 98mySchema.ldif, but they will be stored in 99user.ldif on the replica servers.

After the schema has been replicated during consumer initialization, modifying the schema in cn=schema on the master will also replicate the entire schema to the consumer. Therefore, any modifications to the master schema through the command line utilities or through the console will be replicated to the consumers. These modifications will be stored in 99user.ldif on the master, and by the same mechanism as above, they will also be stored in 99user.ldif on the consumers.

Modifying Replicated Schema Files

The replication mechanism cannot detect any changes you make directly to the LDIF files that contain the schema. Therefore, if you update your schema as described in "Modifying the Schema Files", your changes will not be replicated to consumers even after restarting the master.

Directory Server 5.2 provides the following script to "push" the changes in a schema file to consumers:

Windows platforms	cd ServerRoot bin\slapd\admin\bin\perl slapd-serverID\schema_push.pl
Other Installations	# ServerRoot/slapd-serverID/schema_push.pl

Use the following procedure to modify the schema files on a master server:

1. Add a new schema file or modify an existing one in the schema directory:

ServerRoot/slapd-serverID/config/schema

Schema files in this directory are writable only by the system user defined during installation. For more information, see "Modifying the Schema Files".

2. Run the schema_push.pl script with the appropriate command given above. This script does not actually "push" the schema to replicas, instead it writes a special attribute into the schema files so that they will be replicated as soon as they are loaded.
3. Restart the server. The server will load all schema files and the replication mechanism will replicate the new schema to its consumers.

Limiting Schema Replication

By default, whenever the replication mechanism replicates the schema, it sends the entire schema to its consumers. There are two situations where this is not desirable:

• Modifications to cn=schema using the console or from the command-line are limited to the user-defined schema elements, all of the standard schema is unchanged. If you modify the schema often, sending the large set of unchanged schema elements every time has a performance impact. You may improve replication and server performance by replicating only the user-defined schema elements.
• When a master on Directory Server 5.2 replicates to a consumer on Directory Server 5.1, the schema for the configuration attributes of these versions differ and create conflicts. In this case, you must replicate only the user-defined schema elements, as described below.

Use the following command to limit schema replication so that only the user-defined schema is replicated:

ldapmodify -h host -p port -D "cn=Directory Manager" -w password
dn: cn=config
changetype: modify
replace: nsslapd-schema-repl-useronly
nsslapd-schema-repl-useronly: on

The default value of off will make the entire schema be replicated when necessary.