Chapter 9   Extending the Directory Schema


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

• Overview of Extending Schema

• Turning Schema Checking On and Off

• Managing Object Classes

• Managing Attributes

Overview of Extending 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 iPlanet 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 iPlanet Directory Server Deployment Guide. For information on standard attributes and object classes, see the iPlanet Directory Server Schema Reference.

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

1. Create new attributes. See "Creating Attributes" for information.

2. Create an object class to contain the new attributes and add the attributes to the object class. See "Creating Object Classes" for information.

Managing Attributes

---

Through iPlanet Directory Server Console, you can view all attributes in your schema and you can create, edit, and delete your attribute extensions to the schema. The following sections describe how to manage attributes:

• "Viewing Attributes"

• "Creating Attributes"

• "Editing Attributes"

• "Deleting Attributes"

For information on managing object classes, see "Managing Object Classes".

Viewing Attributes

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

1. On the iPlanet Directory Server Console, select the Configuration tab.

2. In the left navigation tree, select the Schema folder and then select the Attributes tab in the right pane.

   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 table describes 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 an object, such as an object class or an attribute. If you do not specify an OID, the iPlanet Directory Server automatically uses attribute_name-oid. For example, if you create the attribute birthdate without supplying an OID, the iPlanet Directory Server automatically uses birthdate-oid as the OID. 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/iana/.
   Syntax	The syntax describes the allowed format of values for this attribute the possible syntaxes are listed in Table 9-2.
   Multi	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    Attributes Syntax Definitions
   
   

   Syntax and OID	Definition
   Binary (formerly bin)	Indicates that values for this attribute are binary.
   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 exactly two printable string characters, 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 are not 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 are 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, TX 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 are in the form of a URL, introduced by a string such as http://, https://, ftp, LDAP. The URI has the same behavior as IA5String. See RFC 2396.

Creating Attributes

You can use iPlanet Directory Server Console to create new attributes. After adding new attributes to your schema, you must create a new object class to contain them. See "Creating Object Classes" for information.

To create a new attribute:

1. Display the Attributes tab.

   This procedure is explained in "Viewing Attributes".

2. Click Create.

   The Create Attribute dialog box is displayed.

3. Enter a unique name for the attribute in the Attribute Name text box.

4. Enter an object identifier for the attribute in the Attribute OID (Optional) text box.

   OIDs are described in Table 9-1.

5. Select a syntax that describes the data to be held by the attribute from the Syntax drop-down menu.

   Available syntaxes are described in Table 9-1.

6. If you want the attribute to be multi-valued, select the Multi-Valued checkbox.

   The iPlanet Directory Server allows more than one instance of a multi-valued attribute per entry.

7. Click OK.

Editing Attributes

You can edit only attributes you have created. You cannot edit standard attributes.

To edit an attribute:

1. Display the Attributes tab.

   This procedure is explained in "Viewing Attributes".

2. Select the attribute that you want to edit in the User Defined Attributes table and click Edit.

   The Edit Attribute dialog box is displayed.

3. To change the attribute's name, enter a new one in the Attribute Name text box.

4. To change the attribute's object identifier, enter a new one in the Attribute OID (Optional) text box.

   OIDs are described in Table 9-1.

5. To change the syntax that describes the data to be held by the attribute, choose a new one from the Syntax drop-down menu.

6. Available syntaxes are described in Table 9-1.

7. To make the attribute multivalued, select the Multi-Valued checkbox.

   The iPlanet Directory Server allows more than one instance of a multivalued attribute per entry.

8. When you have finished editing the attribute, click OK.

Deleting Attributes

You can delete only attributes that you have created. You cannot delete standard attributes.

To delete an attribute:

1. Display the Attributes tab.

   This procedure is explained in "Viewing Attributes".

2. In the User Defined Attributes table, select the attribute and click Delete.

3. If prompted, confirm the delete.

   The server immediately deletes the attribute. There is no undo.

Managing Object Classes

---

You can use iPlanet Directory Server Console to manage your schema's object classes. Through the Console, you can view all of your schema's object classes and create, edit, and delete your object class extensions to the schema. The following sections describe how to manage object classes:

• "Viewing Object Classes"

• "Creating Object Classes"

• "Editing Object Classes"

• "Deleting Object Classes"

For information on managing attributes, see "Managing Attributes".

Viewing Object Classes

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

1. On the iPlanet Directory Server Console, select the Configuration tab.

2. In the navigation tree, select the Schema folder and then select the Object Classes tab in the right pane.

3. In the Object Classes list, select the object class that you want to view.

   The other fields in the tab display information about the standard or user-defined object class you selected.

The fields of the Object Classes tab are described in the following table.

Table 9-3    Fields of the Object Classes Tab

Field	Description
Parent	The parent identifies the object class from which an object class inherits its attributes and structure. For example, the parent object for the inetOrgPerson object class is the organizationalPerson object. That means that an entry with the object class inetOrgPerson automatically inherits the required and allowed attributes from the object class organizationalPerson. 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	The object identifier of the object class. An OID is a string, usually of dotted decimal numbers, that uniquely identifies an object, such as an object class or an attribute. If you do not specify an OID, the iPlanet Directory Server automatically uses ObjectClass_name-oid. For example, if you create the object class division without supplying an OID, the iPlanet Directory Server automatically uses division-oid as the OID. 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/iana/.
Object Classes	This list contains all of the standard and user-defined object classes in the iPlanet Directory Server schema.
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.

Creating Object Classes

You create an object class by giving it a unique name, selecting a parent object for the new object class, and adding required and optional attributes.

To create an object class:

1. Display the Object Classes tab.

   This procedure is explained in "Viewing Object Classes".

2. Click Create on the Object Classes tab.

   The Create Object Class dialog box is displayed.

3. Enter a unique name for the object class in the Name text box.

4. Enter an object identifier for the new object class in the OID (Optional) text box.

   OIDs are described in Table 9-3.

5. Select a parent object for the object class from the Parent drop-down menu.

   You can choose from any existing object class. See Table 9-3 for more information on parent object classes.

6. To add an attribute that must be present in entries that use the new object class, highlight the attribute in the Available Attributes list and then click the Add button to the left of the Required Attributes box.

   You can use either the standard attributes or create new ones. For information, see "Managing Attributes".

7. To add an attribute that may be present in entries that use the new object class, highlight the attribute in the Available Attributes list and then click the Add button to the left of the Allowed Attributes box.

8. To remove an attribute that you previously added, highlight the attribute in the Required Attributes list or the Allowed Attributes list and then click the corresponding Remove button.

   You cannot remove either allowed or required attributes that are inherited from the parent object classes.

9. When you are satisfied with your object class definition, click OK to dismiss the dialog box.

Editing Object Classes

You can use iPlanet Directory Server Console to edit object classes that you previously created. You cannot edit a standard object class.

To edit an object class:

1. Display the Object Classes tab.

   This procedure is explained in "Viewing Object Classes".

2. Select the object class that you want to edit from the Object Classes list and click Edit.

   The Edit Object Class dialog box is displayed.

3. To change the name of the object class, enter the new name in the Name text box.

4. To change the object identifier for the object class, enter the new OID in the OID (Optional) text box.

   OIDs are described in Table 9-3.

5. To change the parent object for the object class, select the new parent from the Parent pull-down menu.

6. To add an attribute that must be present in entries that use the new object class, highlight the attribute in the Available Attributes list and then click the Add button to the left of the Required Attributes box.

   You can either use the standard attributes or create new ones. For information, see "Managing Attributes".

7. To add an attribute that may be present in entries that use the new object class, highlight the attribute in the Available Attributes list and then click the Add button to the left of the Allowed Attributes box.

8. To remove an attribute that you previously added, highlight the attribute in the Required Attributes list or the Allowed Attributes list and then click the corresponding Remove button.

   You cannot remove either allowed or required inherited attributes.

9. When you are satisfied with you the object class definition, click OK to dismiss the dialog box.

Deleting Object Classes

You can delete only object classes that you have created. You cannot delete standard object classes.

To delete an object class:

1. Display the Object Classes tab.

   This procedure is explained in "Viewing Object Classes".

2. Select the object class that you want to remove and click Delete.

3. If prompted, confirm the delete.

   The server immediately deletes the object class. There is no undo.

Turning Schema Checking On and Off

---

When schema checking is on, the iPlanet Directory Server ensures that:

• The object classes and attributes you are using are defined in the directory schema.

• The attributes required for an object class are contained in the entry.

• Only attributes allowed by the object class are contained in the entry.

Schema checking is turned on by default in the iPlanet Directory Server, and you should always run the iPlanet Directory Server with schema checking turned on. The only case where you might want to turn schema checking off is to accelerate LDAP import operations. However, there is a risk of importing entries that do not conform to the schema. Consequently, it is impossible to search for these entries.

To turn schema checking on and off:

1. On the iPlanet Directory Server Console, select the Configuration tab.

2. Highlight the server icon at the top of the navigation tree, then select the Settings tab in the right pane.

3. To enable schema checking, check the "Enable Schema Checking" checkbox; clear it to turn off schema checking.

4. Click Save.

You can also turn schema checking on and off by using the nsslapd-schemacheck attribute. For information, see the iPlanet Directory Server Configuration, Command, and File Reference.