12.9. Creating Custom Schema Files

Schema files are simple LDIF files which define the cn=schema entry. Each attribute and object class is added as an attribute to that entry. Here are the requirements for creating a schema file:
  • The first line must be dn: cn=schema.
  • The schema file can include both attributes and object classes, but it can also include only one or the other.
  • If both attributes and object classes are defined in the style, all of the attributes must be listed in the file first, then the object classes.
  • The object classes can use attributes defined in other schema files.
  • The file must be named in the format [1-9][0-9]text.ldif.
    The file must always begin with two numbers. Numerically, the schema file cannot be loaded before the core configuration schema (which begin with 00 and 01).
    Also, the Directory Server always writes its custom schema to the numerically and alphabetically highest named schema file in the schema directory. It expects this file to be 99user.ldif. If this file is not 99user.ldif, the server can experience problems. So, always make sure custom schema files are at least alphabetically lower than 99user.ldif. The name 99alpha.ldif is okay; the name 99zzz.ldif is not.
Practices for creating schema files are described in more detail in the Deployment Guide.
Attributes are defined in the schema file as attributetypes attributes to the schema, with five components:
  • An OID, usually a dot-separated number
  • A unique name, in the form NAME name
  • A description, in the form DESC description
  • The OID for the syntax of the attribute values, discussed in Section 12.1.3.1, “Directory Server Attribute Syntaxes”, in the form SYNTAX OID
  • Optionally, the source where the attribute is defined
For example:
attributetypes: ( 1.2.3.4.5.6.1 NAME 'dateofbirth' DESC 'For employee birthdays' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUED X-ORIGIN 'Example defined')
Likewise, object classes are defined as values of objectclasses attributes, although there is slightly more flexibility in how the object class is defined. The only required configurations are the name and OID for the object class; all other configuration depends on the needs for the object class:
  • An OID, usually a dot-separated number
  • A unique name, in the form NAME name
  • A description, in the form DESC description
  • The superior, or parent, object class for this object class, in the form SUP object_class; if there is no related parent, use SUP top
  • The word AUXILIARY, which gives the type of entry to which the object class applies; AUXILIARY means 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 ($)
For example:
objectclasses: ( 2.16.840.1133730.2.123 NAME 'examplePerson' DESC 'Example Person Object Class' SUP inetOrgPerson AUXILIARY  MUST cn MAY (exampleDateOfBirth $ examplePreferredOS) )
Example 12.4, “Example Schema File” shows a simplified schema file.

Example 12.4. Example Schema File

dn: cn=schema
attributetypes: ( 2.16.840.1133730.1.123 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.1133730.2.123 NAME 'examplePerson' DESC 'Example Person Object Class' SUP inetOrgPerson AUXILIARY MAY (dateofbirth) )
Custom schema files should be added to the Directory Server instance's schema directory, /etc/dirsrv/slapd-instance/schema. The schema in these files are not loaded and available to the server unless the server is restarted or a dynamic reload task is run.

Important

If you want to use a standard schema from the /usr/share/data/ directory, copy the schema file to the /usr/share/dirsrv/schema/ directory. If you require that a standard schema is only available to a specific instance, copy the schema file to the /etc/dirsrv/slapd-instance_name/schema/ directory, but use a different file name in the destination directory. Otherwise, Directory Server renames the file during an upgrade and appends the .bak suffix.