Chapter 12. Managing the Directory Schema
12.1. Overview of Schema
12.1.1. Default Schema Files
/usr/share/dirsrv/schema/directory. The files in this directory are used as templates for new Directory Server instances. Adding a new schema into this directory will make it available to any new instances.
12.1.2. Object Classes
inetOrgPerson), groups (
groupOfNames), locations (
locality), organizations and divisions (
organizationalUnit), and equipment (
objectclassesline, then followed by its OID, name, a description, its direct superior object class (an object class which is required to be used in conjunction with the object class and which shares its attributes with this object class), and the list of required (
MUST) and allowed (
Example 12.1. person Object Class Schema Entry
objectClasses: ( 18.104.22.168 NAME 'person' DESC 'Standard LDAP objectclass' SUP top MUST ( sn $ cn ) MAY ( description $ seeAlso $ telephoneNumber $ userPassword ) X-ORIGIN 'RFC 4519' )
MUSTkeyword in the schema) and of allowed attributes (
MAYkeyword in the schema). Required attributes must be present in entries using the specified object class, while allowed attributes are permissible and available for the entry to use, but are not required for the entry to be valid.
personobject class requires the
objectClassattributes and allows the
inetOrgPersonobject class. In that case, the entry must also include the superior object class for
organizationalPerson, and the superior object class for
organizationalPerson, which is
objectClass: top objectClass: person objectClass: organizationalPerson objectClass: inetOrgPerson
objectclassesattribute for the
objectclassesattribute has the format:
objectclasses: ( definition )
- An OID, usually a dot-separated number
- A unique name, in the form
- A description, in the form
- The superior, or parent, object class for this object class, in the form
SUPobject_class; if there is no related parent, use
- The word
AUXILIARY, which gives the type of entry to which the object class applies;
AUXILIARYmeans it can apply to any entry
- A list of required attributes, preceded by the word
MUST; to include multiple attributes, enclose the group in parentheses and separate with attributes with dollar signs ($)
- A list of allowed attributes, preceded by the word
MAY; to include multiple attributes, enclose the group in parentheses and separate with attributes with dollar signs ($)
/etc/dirsrv/slapd-instance_name/schema/99user.ldifwhen using the command line or the web console to modify
cnattribute is used to store a person's full name, such as
cn: John Smith.
givenname: John surname: Smith mail: email@example.com
- syntax matching rule (optional)
- substring matching rules (optional)
- ordering rule (optional)
- description (optional)
- single-valued or multi-valued attribute
- details about where the attribute is defined
uidAttribute Schema Entry”.
uid Attribute Schema Entry
( 0.9.2342.19200300.100.1.1 NAME ( 'uid' 'userid' ) EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 22.214.171.124.4.1.14126.96.36.199.15 X-ORIGIN 'RFC 4519' )
188.8.131.52. Directory Server Attribute Syntaxes
12.1.4. Extending the Schema
99user.ldif. It is also possible to create a new, separate schema file and include it with the default schema files.
- Planning and defining OIDs for the new schema. Schema elements are recognized by the server by their OID, so it is important for the OIDs to be unique and organized. Directory Server itself does not manage OIDs, but there are some best practices described in Section 12.2, “Managing Object Identifiers”.
- Create the new attributes. Attribute definitions require a name, a syntax (the allowed format of the values), an OID, and a description of whether the attribute can only be used once per entry or multiple times.
- Create an object class to contain the new attributes. An object class lists the required attributes for that entry type and the allowed (permissible) attributes. Because the default schema should never be altered, if any new attributes are created, then they should be added to a custom object class.
/usr/share/dirsrv/schema/. Become familiar with the available schema; then plan what information attributes are missing and how best to fill those gaps with custom attributes. Planning the schema is covered in the Deployment Guide.
- 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.
- Do not modify any existing definitions of attributes or object classes.
12.1.5. Schema Replication
cn=schemasub-tree, Directory Server stores the changes in the local
/etc/dirsrv/slapd-instance_name/schema/99user.ldiffile, including a change state number (CSN). The updated schema is not automatically replicated to other replicas. The schema replication starts when directory content is updated in the replicated tree. For example, if you update a user or group entry after modifying the schema, the supplier compares the CSN stored in the
nsSchemaCSNattribute with the one on the consumer. If the remote CSN is lower than the one on the supplier, the schema is replicated to the consumer. For a successful replication, all object classes and attribute types on the supplier must be a superset of the consumer's definition.
Example 12.3. Schema subsets and supersets
demoobject class allows the
demoobject class allows the
demoobject class on
server1is a superset of the object class on
server2. During the validation phase, when the schema is being replicated or accepted, Directory Server retrieves the superset definitions. For example, if a consumer detects that an object class in the local schema allows less attributes than the object class in the supplier schema, the local schema is updated.
nsSchemaCSNattributes are identical on both servers and no longer compared at the beginning of a replication session.
- The schema on one host is a subset of the schema of another host.For example, in Example 12.3, “Schema subsets and supersets”, the schema definition of the
demoobject class on
server2is a subset of the object class on
server1. Subsets can also occur for attributes (a single-value attribute is a subset of a multi-value attribute) and attribute syntaxes (
IA5is a subset of
- When definitions in supplier schema and consumer schema need to be merged.Directory Server does not support merging schemas. For example, if an object class on one server allows the
a4on the other, the schemas are not subsets and cannot be merged.
- Schema files other than
/etc/dirsrv/slapd-instance_name/schema/99user.ldifare used.Directory Server enables you to add additional schema files in the
/etc/dirsrv/slapd-instance_name/schema/directory. However, only the CSN in the
99user.ldiffile is updated. For this reasons, other schema file are only used locally and are not automatically transferred to replication partners. Copy the updated schema file manually to the consumers and reload the schema. For details, see Section 12.10, “Dynamically Reloading Schema”.To avoid duplicate schema definitions and to enable automatic replication, store all custom schema in the
/etc/dirsrv/slapd-instance_name/schema/99user.ldiffile. For further information about creating custom schema files, see Section 12.9, “Creating Custom Schema Files”.