3.4. Customizing the Schema

The standard schema can be extended if it is too limited for the directory needs. The web console in Directory Server can be used to extend the schema by easily adding attributes and object classes. It is also possible to create an LDIF file and add schema elements manually. For more information, see the Red Hat Directory Server Administration Guide.
Keep the following rules in mind when customizing the Directory Server schema:
  • Keep the schema as simple as possible.
  • Reuse existing schema elements whenever possible.
  • Minimize the number of mandatory attributes defined for each object class.
  • Do not define more than one object class or attribute for the same purpose (data).
  • Do not modify any existing definitions of attributes or object classes.

Note

When customizing the schema, never delete or replace the standard schema. Doing so can lead to compatibility problems with other directories or other LDAP client applications.
Custom object classes and attributes are defined in the 99user.ldif file. Each individual instance maintains its own 99user.ldif file in the /etc/dirsrv/slapd-instance_name/schema/ directory. It is also possible to create custom schema files and dynamically reload the schema into the server.

3.4.1. When to Extend the Schema

While the object classes and attributes supplied with the Directory Server should meet most common corporate needs, a given object class may not store specialized information about an organization. Also, the schema may need extended to support the object classes and attributes required by an LDAP-enabled application's unique data needs.

3.4.2. Getting and Assigning Object Identifiers

Each LDAP object class or attribute must be assigned a unique name and object identifier (OID). When a schema is defined, the elements require a base OID which is unique to your organization. One OID is enough to meet all schema needs. Simply add another level of hierarchy to create new branches for attributes and object classes. Getting and assigning OIDs in schema involves the following steps:
  1. Obtain an OID 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.
  2. Create an OID registry to track OID assignments.
    An OID registry is a list of the OIDs and descriptions of the OIDs used in the directory schema. This ensures that no OID is ever used for more than one purpose. Then publish the OID registry with the schema.
  3. Create branches in the OID tree to accommodate schema elements.
    Create at least two branches under the OID branch or the directory schema, using OID.1 for attributes and OID.2 for object classes. To define custom matching rules or controls, add new branches as needed (OID.3, for example).

3.4.3. Naming Attributes and Object Classes

When creating names for new attributes and object classes, make the names as meaningful as possible. This makes the schema easier to use for Directory Server administrators.
Avoid naming collisions between schema elements and existing schema elements by including a unique prefix on all schema elements. For example, Example Corp. might add the prefix example before each of their custom schema elements. They might add a special object class called examplePerson to identify Example Corp. employees in their directory.

3.4.4. Strategies for Defining New Object Classes

There are two ways to create new object classes:
  • Create many new object classes, one for each object class structure to which to add an attribute.
  • Create a single object class that supports all of the custom attributes created for the directory. This kind of object class is created by defining it as an auxiliary object class.
It may be easiest to mix the two methods.
For example, suppose an administrator wants to create the attributes exampleDateOfBirth, examplePreferredOS, exampleBuildingFloor, and exampleVicePresident. A simple solution is to create several object classes that allow some subset of these attributes.
  • One object class, examplePerson, is created and allows exampleDateOfBirth and examplePreferredOS. The parent of examplePerson is inetOrgPerson.
  • A second object class, exampleOrganization, allows exampleBuildingFloor and exampleVicePresident. The parent of exampleOrganization is the organization object class.
The new object classes appear in LDAPv3 schema format as follows: 
objectclasses: ( 2.16.840.1.117370.999.1.2.3 NAME 'examplePerson' DESC 'Example Person Object Class'
     SUP inetorgPerson MAY (exampleDateOfBirth $ examplePreferredOS) )

objectclasses: ( 2.16.840.1.117370.999.1.2.4 NAME 'exampleOrganization' DESC 'Organization Object Class'
     SUP organization MAY (exampleBuildingFloor $ exampleVicePresident) )
Alternatively, create a single object class that allows all of these attributes and use it with any entry which needs these attributes. The single object class appears as follows: 
objectclasses: (2.16.840.1.117370.999.1.2.5 NAME 'exampleEntry' DESC 'Standard Entry Object Class' SUP top
     AUXILIARY MAY (exampleDateOfBirth $ examplePreferredOS $ exampleBuildingFloor $ exampleVicePresident) )
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 example (2.16.840.1.117370) is based on the former Netscape OID prefix. To create custom object classes, obtain an OID as described in Section 3.4.2, “Getting and Assigning Object Identifiers”.
There are several different ways to organize new object classes, depending on the organization environment. Consider the following when deciding how to implement new object classes:
  • Multiple object classes result in more schema elements to create and maintain.
    Generally, the number of elements remains small and needs little maintenance. However, it may be easier to use a single object class if there are more than two or three object classes added to the schema.
  • Multiple object classes require a more careful and rigid data design.
    Rigid data design forces attention to the object class structure under which every piece of data is placed, which can be either helpful or cumbersome.
  • Single object classes simplify data design when there is data that can be applied to more than one type of object class, such as both people and asset entries.
    For example, a custom preferredOS attribute may be set on both a person and a group entry. A single object class can allow this attribute on both types of entries.
  • Avoid required attributes for new object classes.
    Specifying require instead of allow for attributes in new object classes can make the schema inflexible. When creating a new object class, use allow rather than require as much as possible.
    After defining a new object class, decide what attributes it allows and requires, and from what object classes it inherits attributes.

3.4.5. Strategies for Defining New Attributes

For both application compatibility and long-term maintenance, 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 or check out the Directory Server Schema Guide. However, if the standard schema does not contain all the information you need, then add new attributes and new object classes.
For example, a person entry may need more attributes than the person, organizationalPerson, or inetOrgPerson object classes support by default. As an example, no attribute exists within the standard Directory Server schema to store birth dates. A new attribute, dateOfBirth, can be created and set as an allowed attribute within a new auxiliary object class, examplePerson. 
attributetypes: ( dateofbirth-oid NAME 'dateofbirth' DESC 'For employee birthdays'
     SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 X-ORIGIN 'Example defined')

objectclasses: ( 2.16.840.1.117370.999.1.2.3 NAME 'examplePerson' DESC 'Example Person Object Class'
     SUP inetorgPerson MAY (exampleDateOfBirth $ cn) X-ORIGIN 'Example defined')
One important thing to remember: Never add or delete custom attributes to standard schema elements. If the directory requires custom attributes, add custom object classes to contain them.

3.4.6. Deleting Schema Elements

Do not delete the schema elements included by default with Directory Server. Unused schema elements represent no operational or administrative overhead. Deleting parts of the standard LDAP schema can cause compatibility problems with future installations of Directory Server and other directory-enabled applications.
However, unused custom schema elements can be deleted. Before removing the object class definitions from the schema, modify each entry using the object class. Removing the definition first might prevent the entries that use the object class from being modified later. Schema checks on modified entries also fails unless the unknown object class values are removed from the entry.

3.4.7. Creating Custom Schema Files

Administrators can create custom schema files for the Directory Server to use, in addition to the 99user.ldif file provided with Directory Server. These schema files hold new, custom attributes and object classes that are specific to the organization. The new schema files should be located in the schema directory, /etc/dirsrv/slapd-instance_name/schema/.
All standard attributes and object classes are loaded only after custom schema elements have been loaded.

Note

Custom schema files should not be numerically or alphabetically higher than 99user.ldif or the server could experience problems.
After creating custom schema files, there are two ways for the schema changes to be distributed among all servers:
  • Manually copy these custom schema files to the instance's schema directory, /etc/dirsrv/slapd-instance/schema. To load the schema, restart the server or reload the schema dynamically by running the schema-reload.pl script.
  • Modify the schema on the server with an LDAP client such as the web console or ldapmodify.
  • If the server is replicated, then allow the replication process to copy the schema information to each of the consumer servers.
    With replication, all of the replicated schema elements are copied into the consumer servers' 99user.ldif file. To keep the schema in a custom schema file, like 90example_schema.ldif, the file has to be copied over to the consumer server manually. Replication does not copy schema files.
If these custom schema files are not copied to all of the servers, the schema information are only replicated to the replica (consumer server) when changes are made to the schema on the supplier server using an LDAP client such as the web console or ldapmodify.
When the schema definitions are replicated to a consumer server where they do not already exist, they are stored in the 99user.ldif file. The directory does not track where schema definitions are stored. Storing schema elements in the 99user.ldif file of consumers does not create a problem as long as the schema is maintained on the supplier server only.
If the custom schema files are copied to each server, changes to the schema files must be copied again to each server. If the files are not copied over again, it is possible the changes will 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 copied from the supplier and again in the 99user.ldif file after replication.
For more information about replicating schema, see Section 7.4.4, “Schema Replication”.

3.4.8. Custom Schema Best Practices

When using schema files, be sure to create schema which will be compatible and easy to manage.

3.4.8.1. Naming Schema Files

When naming custom schema files, use the following naming format: 
[00-99]yourName.ldif
Name custom schema files lower (numerically and alphabetically) than 99user.ldif. This lets Directory Server write to 99user.ldif, both through LDAP tools and the web console.
The 99user.ldif file contains attributes with an X-ORIGIN value of 'user defined'; however, the Directory Server writes all 'user defined' schema elements to the highest named file, numerically then alphabetically. If there is a schema file called 99zzz.ldif, the next time the schema is updated (either through LDAP command-line tools or the web console) all of the attributes with an X-ORIGIN value of 'user defined' are written to 99zzz.ldif. The result is two LDIF files that contain duplicate information, and some information in the 99zzz.ldif file might be erased.

3.4.8.2. Using 'user defined' as the Origin

Do not use 'user defined' in the X-ORIGIN field of custom schema files (such as 60example.ldif), because 'user defined' is used internally by the Directory Server when a schema is added over LDAP. In custom schema files, use something more descriptive, such as 'Example Corp. defined'.
However, if the custom schema elements are added directly to the 99user.ldif manually, use 'user defined' as the value of X-ORIGIN. If a different X-ORIGIN value is set, the server simply may overwrite it.
Using an X-ORIGIN of value 'user defined' ensures that schema definitions in the 99user.ldif file are not removed from the file by the Directory Server. The Directory Server does not remove them because it relies on an X-ORIGIN of value 'user defined' to tell it what elements should reside in the 99user.ldif file.
For example: 
attributetypes: ( exampleContact-oid NAME 'exampleContact'
DESC 'Example Corporate contact'
SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
X-ORIGIN 'Example defined')
After the Directory Server loads the schema entry, it appears as follows: 
attributetypes: ( exampleContact-oid NAME 'exampleContact'
DESC 'Example Corporate contact'
SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
X-ORIGIN ('Example defined' 'user defined') )

3.4.8.3. Defining Attributes before Object Classes

When adding new schema elements, all attributes need to be defined before they can be used in an object class. Attributes and object classes can be defined in the same schema file.

3.4.8.4. Defining Schema in a Single File

Each custom attribute or object class 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 (as the server loads the schema in numerical order first, then alphabetical order). Decide how to keep from having schema in duplicate files:
  • Be careful with what schema elements are included in each schema file.
  • Be careful in naming and updating the schema files. When schema elements are edited through LDAP tools, the changes are automatically written to the last file (alphabetically). Most schema changes, then, write to the default file 99user.ldif and not to the custom schema file, such as 60example.ldif. Also, the schema elements in 99user.ldif override duplicate elements in other schema files.
  • Add all the schema definitions to the 99user.ldif file. This is useful if your are managing the schema through the web console.