8. Schema Specification
This chapter describes how to extend the schema used by slapd(8). The first section, Distributed Schema Files details optional schema definitions provided in the distribution and where to obtain other definitions. The second section, Extending Schema, details how to define new schema items.
8.1. Distributed Schema Files
OpenLDAP is distributed with a set of schema specifications for your use. Each set is defined in a file suitable for inclusion (using the include directive) in your slapd.conf(5) file. These schema files are normally installed in the /usr/local/etc/openldap/schema directory.
| File | Description |
| core.schema | OpenLDAP core (required) |
| cosine.schema | Cosine and Internet X.500 (useful) |
| inetorgperson.schema | InetOrgPerson (useful) |
| misc.schema | Assorted (experimental) |
| nadf.schema | North American Directory Forum (FYI) |
| nis.schema | Network Information Services (FYI) |
| openldap.schema | OpenLDAP Project (experimental) |
To use any of these schema files, you only need to include the the desired file in the global definitions portion of your slapd.conf(5) file. For example:
# include schema
include /usr/local/etc/openldap/schema/core.schema
include /usr/local/etc/openldap/schema/cosine.schema
include /usr/local/etc/openldap/schema/inetorgperson.schema
Additional files may be available. Please consult the OpenLDAP FAQ (http://www.openldap.org/faq/).
Note: You should not modify any of the schema items defined in provided files.
8.2. Extending Schema
Schema used by slapd(8) may be extended to support additional syntaxes, matching rules, attribute types, and object classes. This chapter details how to add attribute types and object classes using the syntaxes and matching rules already supported by slapd. slapd can also be extended to support additional syntaxes and matching rules, but this requires some programming and hence is not discussed here.
There are five steps to defining new schema:
- obtain Object Identifer
- choose a name prefix
- create local schema file
- define custom attribute types (if necessary)
- define custom object classes
8.2.1. Object Identifiers
Each schema element is identified by a globally unique
| OID | Assignment |
| 1.1 | Organization's OID |
| 1.1.1 | SNMP Elements |
| 1.1.2 | LDAP Elements |
| 1.1.2.1 | AttributeTypes |
| 1.1.2.1.1 | myAttribute |
| 1.1.2.2 | ObjectClasses |
| 1.1.2.2.1 | myObjectClass |
You are, of course, free to design a hierarchy suitable to your organizational needs under your organization's OID. No matter what hierarchy you choose, you should maintain a registry of assignments you make. This can be a simple flat file or a something more sophisticated such as the OpenLDAP OID Registry (http://www.openldap.org/faq/index.cgi?file=197).
For more information about Object Identifers (and a listing service) see http://www.alvestrand.no/harald/objectid/.
-
Under no circumstances should you use a fictious OID!
To obtain a fully registered OID at no cost, apply for an OID under Internet Assigned Numbers Authority (IANA) maintained Private Enterprise arch. Any private enterprise (organization) may request an OID to be assigned under this arch. Just fill out the IANA form at http://www.iana.org/cgi-bin/enterprise.pl and your official OID will be sent to you usually within a few days. Your base OID will be something like 1.3.6.1.4.1.X were X is an integer.
Note: Don't let the "MIB/SNMP" statement on the IANA page confuse you. OIDs obtained using this form may be used for any purpose including identifying LDAP schema elements.
8.2.2. Name Prefix
In addition to assigning a unique object identifier to each schema element, you should provide a least one textual name for each element. The name should be both descriptive and not likely to clash with names of other schema elements. In particular, any name you choose should not clash with present or future Standard Track names.
To reduce (but not eliminate) the potential for name clashes, the convention is to prefix names of non-Standard Track with a few letters to localize the changes to your organization. The smaller the organization, the longer your prefix should be.
In the examples below, we have choosen a short prefix 'my' (to save space). Such a short prefix would only be suitable for a very large, global organization. For a small, local organization, we recommend something like 'deFirm' (German company) or 'comExample' (elements associated with organization associated with example.com).
8.2.3. Local schema file
The objectclass and attributeTypes configuration file directives can be used to define schema rules on entries in the directory. It is customary to create a file to contain definitions of your custom schema items. We recommend you create a file local.schema in /usr/local/etc/openldap/schema/local.schema and then include this file in your slapd.conf(5) file immediately after other schema include directives.
# include schema
include /usr/local/etc/openldap/schema/core.schema
include /usr/local/etc/openldap/schema/cosine.schema
include /usr/local/etc/openldap/schema/inetorgperson.schema
# include local schema
include /usr/local/etc/openldap/schema/local.schema
8.2.4. Attribute Type Specification
The attributetype directive is used to define a new attribute type. The directive uses the same Attribute Type Description (as defined in RFC2252) used by the attributeTypes attribute found in the subschema subentry, e.g.:
attributetype <RFC2252 Attribute Type Description>
where Attribute Type Description is defined by the following
AttributeTypeDescription = "(" whsp
numericoid whsp ; AttributeType identifier
[ "NAME" qdescrs ] ; name used in AttributeType
[ "DESC" qdstring ] ; description
[ "OBSOLETE" whsp ]
[ "SUP" woid ] ; derived from this other
; AttributeType
[ "EQUALITY" woid ; Matching Rule name
[ "ORDERING" woid ; Matching Rule name
[ "SUBSTR" woid ] ; Matching Rule name
[ "SYNTAX" whsp noidlen whsp ] ; see section 4.3
[ "SINGLE-VALUE" whsp ] ; default multi-valued
[ "COLLECTIVE" whsp ] ; default not collective
[ "NO-USER-MODIFICATION" whsp ]; default user modifiable
[ "USAGE" whsp AttributeUsage ]; default userApplications
whsp ")"
AttributeUsage =
"userApplications" /
"directoryOperation" /
"distributedOperation" / ; DSA-shared
"dSAOperation" ; DSA-specific, value depends on server
where whsp is a space (' '), numericoid is a globally unique OID in numeric form (e.g. 1.2.3), qdescrs is one or more names, woid is either the name or OID, and noidlen is an optional length specifier (e.g {10}).
For example, the attribute types name and cn are defined in core.schema as:
attributeType ( 2.5.4.41 NAME 'name'
EQUALITY caseIgnoreMatch
SUBSTR caseIgnoreSubstringsMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{32768} )
attributeType ( 2.5.4.3 NAME
( 'cn' $ 'commonName' ) SUP name )
Notice that each defines the attribute's OID and descriptive names. Each name is an alias for the OID. slapd(8) returns the first listed name when returning results.
The first attribute, name, has a syntax of directoryString (a UTF-8 encoded Unicode string) with a recommend maximun length. Note that syntaxes are specified by OID. In addition, the equality and substring matching uses case ignore rules. Below are tables listing commonly used supported syntax and matching rules.
| Name | OID | Description |
| binary | 1.3.6.1.4.1.1466.115.121.1.5 | BER/DER data |
| boolean | 1.3.6.1.4.1.1466.115.121.1.7 | boolean value |
| distinguishedName | 1.3.6.1.4.1.1466.115.121.1.12 | DN |
| directoryString | 1.3.6.1.4.1.1466.115.121.1.15 | UTF-8 string |
| IA5String | 1.3.6.1.4.1.1466.115.121.1.26 | ASCII string |
| Integer | 1.3.6.1.4.1.1466.115.121.1.27 | integer |
| Name and Optional UID | 1.3.6.1.4.1.1466.115.121.1.34 | DN plus UID |
| Numeric String | 1.3.6.1.4.1.1466.115.121.1.36 | numeric string |
| OID | 1.3.6.1.4.1.1466.115.121.1.38 | object identifier |
| Octet String | 1.3.6.1.4.1.1466.115.121.1.40 | arbitary octets |
| Printable String | 1.3.6.1.4.1.1466.115.121.1.44 | printable string |
| Name | Type | Description |
| booleanMatch | equality | boolean |
| objectIdentiferMatch | equality | OID |
| distinguishedNameMatch | equality | DN |
| uniqueMemberMatch | equality | DN with optional UID |
| numericStringMatch | equality | numerical |
| numericStringOrderingMatch | ordering | numerical |
| numericStringSubstringsMatch | substrings | numerical |
| caseIgnoreMatch | equality | case insensitive, space insensitive |
| caseIgnoreOrderingMatch | ordering | case insensitive, space insensitive |
| caseIgnoreSubstringsMatch | substrings | case insensitive, space insensitive |
| caseExactMatch | equality | case sensitive, space insensitive |
| caseExactOrderingMatch | ordering | case sensitive, space insensitive |
| caseExactSubstringsMatch | substrings | case sensitive, space insensitive |
| caseIgnoreIA5Match | equality | case insensitive, space insensitive |
| caseIgnoreIA5OrderingMatch | ordering | case insensitive, space insensitive |
| caseIgnoreIA5SubstringsMatch | substrings | case insensitive, space insensitive |
| caseExactIA5Match | equality | case sensitive, space insensitive |
| caseExactIA5OrderingMatch | ordering | case sensitive, space insensitive |
| caseExactIA5SubstringsMatch | substrings | case sensitive, space insensitive |
The second attribute, cn, is a subtype of name hence it inherits the syntax, matching rules, and usage of name. commonName is an alternative name.
Neither attribute is restricted to a single value and both are meant for usage by user applications. You likely won't need to specify other parameters such as OBSOLETE.
The following subsections provide a couple of examples.
8.2.4.1. myUniqueName
Many organizations maintain a single unique name for each user. Though one could use displayName (RFC2798), this attribute is really meant to be controlled by the user, not the organization. We could just copy the definition of displayName from inetorgperson.schema and replace the OID, name, and description, e.g:
attributetype ( 1.1.2.1.1 NAME 'myUniqueName'
DESC 'unique name with my organization'
EQUALITY caseIgnoreMatch
SUBSTR caseIgnoreSubstringsMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
SINGLE-VALUE )
However, if we want this name to be included in name assertions [e.g. (name=*Jane*)], the attribute could alternatively be defined as a subtype of name, e.g.:
attributetype ( 1.1.2.1.1 NAME 'myUniqueName'
DESC 'unique name with my organization'
SUP name )
8.2.4.2. myPhoto
Many organizations maintain a photo of each each user. A myPhoto attribute type could be defined to hold a photo. Of course, one could use just use jpegPhoto (RFC2798) (or a subtype) to hold the photo. However, you can only do this if the photo is in JPEG File Interchange Format. Alternatively, an attribute type which uses the Octet String syntax can be defined, e.g.:
attributetype ( 1.1.2.1.2 NAME 'myPhoto'
DESC 'a photo (application defined format)'
SYNTAX 1.3.6.1.4.1.1466.115.121.1.40
SINGLE-VALUE )
As noted in the description, LDAP has no knowledge of the format of the photo. It's assumed that all applications accessing this attribute agree on the handling of values.
If you wanted to support multiple photo formats, you could define a separate attribute type for each format, prefix the photo with some typing information, or describe the value using
Another alternative is for the attribute to hold a
8.2.5. Object Class Specification
The objectclasses directive is used to define a new object class. The directive uses the same Object Class Description (as defined in RFC2252) used by the objectClasses attribute found in the subschema subentry, e.g.:
objectclass <RFC2252 Object Class Description>
where Object Class Description is defined by the following
ObjectClassDescription = "(" whsp
numericoid whsp ; ObjectClass identifier
[ "NAME" qdescrs ]
[ "DESC" qdstring ]
[ "OBSOLETE" whsp ]
[ "SUP" oids ] ; Superior ObjectClasses
[ ( "ABSTRACT" / "STRUCTURAL" / "AUXILIARY" ) whsp ]
; default structural
[ "MUST" oids ] ; AttributeTypes
[ "MAY" oids ] ; AttributeTypes
whsp ")"
where whsp is a space (' '), numericoid is a globally unique OID in numeric form (e.g. 1.2.3), qdescrs is one or more names, and oids is one or more names and/or OIDs.
8.2.5.1. myPhotoObject
To define an auxiliary object class which allows myPhoto to be added to any existing entry.
objectclass ( 1.1.2.2.1 NAME 'myPhotoObject'
DESC 'mixin myPhoto'
AUXILIARY
MAY myPhoto )
8.2.5.2. myPerson
If your organization would like have a private structural object class to instantiate users, you can subclass one of the existing person classes, such as inetOrgPerson (RFC2798), and add any additional attributes which you desire.
objectclass ( 1.1.2.2.2 NAME 'myPerson'
DESC 'my person'
SUP inetOrgPerson
MUST ( 'myUniqueName' $ 'givenName' )
MAY 'myPhoto' )
The object class inherits the required/allowed attribute types of inetOrgPerson but requires myUniqueName and givenName and allows myPhoto.