2 # Copyright 1999-2003, The OpenLDAP Foundation, All Rights Reserved.
3 # COPYING RESTRICTIONS APPLY, see COPYRIGHT.
5 H1: Schema Specification
7 This chapter describes how to extend the user schema used by
8 {{slapd}}(8). The chapter assumes the reader is familar with the
9 {{TERM:LDAP}}/{{TERM:X.500}} information model.
11 The first section, {{SECT:Distributed Schema Files}} details optional
12 schema definitions provided in the distribution and where to obtain
14 The second section, {{SECT:Extending Schema}}, details how to define
17 The third section, {{SECT:Transferring Schema}} details how you can
18 export schema definitions from an LDAPv3 server and transform it
19 to {{slapd.conf}}(5) format.
22 This chapter does not discuss how to extend system schema used by
23 {{slapd}}(8) as this requires source code modification. System
24 schema includes all operational attribute types or any object class
25 which allows or requires an operational attribute (directly or
29 H2: Distributed Schema Files
31 OpenLDAP is distributed with a set of schema specifications for
32 your use. Each set is defined in a file suitable for inclusion
33 (using the {{EX:include}} directive) in your {{slapd.conf}}(5)
34 file. These schema files are normally installed in the
35 {{F:/usr/local/etc/openldap/schema}} directory.
37 !block table; colaligns="LR"; coltags="F,N"; align=Center; \
38 title="Table 8.1: Provided Schema Specifications"
40 core.schema OpenLDAP {{core}} (required)
41 cosine.schema Cosine and Internet X.500 (useful)
42 inetorgperson.schema InetOrgPerson (useful)
43 misc.schema Assorted (experimental)
44 nis.schema Network Information Services (FYI)
45 openldap.schema OpenLDAP Project (experimental)
48 To use any of these schema files, you only need to include the
49 desired file in the global definitions portion of your
50 {{slapd.conf}}(5) file. For example:
53 > include /usr/local/etc/openldap/schema/core.schema
54 > include /usr/local/etc/openldap/schema/cosine.schema
55 > include /usr/local/etc/openldap/schema/inetorgperson.schema
57 Additional files may be available. Please consult the OpenLDAP
58 FAQ ({{URL:http://www.openldap.org/faq/}}).
60 Note: You should not modify any of the schema items defined
66 Schema used by {{slapd}}(8) may be extended to support additional
67 syntaxes, matching rules, attribute types, and object classes. This
68 chapter details how to add user application attribute types and
69 object classes using the syntaxes and matching rules already supported
70 by slapd. slapd can also be extended to support additional syntaxes,
71 matching rules and system schema, but this requires some programming
72 and hence is not discussed here.
74 There are five steps to defining new schema:
75 ^ obtain Object Identifer
76 + choose a name prefix
77 + create local schema file
78 + define custom attribute types (if necessary)
79 + define custom object classes
82 H3: Object Identifiers
84 Each schema element is identified by a globally unique
85 {{TERM[expand]OID}} (OID). OIDs are also used to identify
87 They are commonly found in protocols described by {{TERM:ASN.1}}. In
88 particular, they are heavily used by the {{TERM[expand]SNMP}} (SNMP).
89 As OIDs are hierarchical, your organization
90 can obtain one OID and branch it as needed. For example,
91 if your organization were assigned OID {{EX:1.1}}, you could branch
94 !block table; colaligns="LR"; coltags="EX,N"; align=Center; \
95 title="Table 8.2: Example OID hierarchy"
97 1.1 Organization's OID
100 1.1.2.1 AttributeTypes
101 1.1.2.1.1 myAttribute
102 1.1.2.2 ObjectClasses
103 1.1.2.2.1 myObjectClass
106 You are, of course, free to design a hierarchy suitable to your
107 organizational needs under your organization's OID. No matter what
108 hierarchy you choose, you should maintain a registry of assignments
109 you make. This can be a simple flat file or something more
110 sophisticated such as the {{OpenLDAP OID Registry}}
111 ({{URL:http://www.openldap.org/faq/index.cgi?file=197}}).
113 For more information about Object Identifers (and a listing service)
114 see {{URL:http://www.alvestrand.no/harald/objectid/}}.
116 .{{Under no circumstances should you hijack OID namespace!}}
118 To obtain a registered OID at {{no cost}}, apply for an OID under
119 the {{ORG[expand]IANA}} (IANA) maintained {{Private Enterprise}}
120 arc. Any private enterprise (organization) may request an OID to
121 be assigned under this arc. Just fill out the {{ORG:IANA}} form
122 at {{URL: http://www.iana.org/cgi-bin/enterprise.pl}} and your
123 official OID will be sent to you usually within a few days. Your
124 base OID will be something like {{EX:1.3.6.1.4.1.X}} where {{EX:X}}
127 Note: Don't let the "MIB/SNMP" statement on the IANA page confuse
128 you. OIDs obtained using this form may be used for any purpose
129 including identifying LDAP schema elements.
131 Alternatively, OID name space may be available from a national
132 authority (e.g., ANSI, BSI).
134 For private experiments, OIDs under {{EX:1.1}} may be used. The
135 OID {{EX:1.1}} arc is regarded as dead name space.
140 In addition to assigning a unique object identifier to each schema
141 element, you should provide a least one textual name for each
142 element. The name should be both descriptive and not likely to
143 clash with names of other schema elements. In particular, any name
144 you choose should not clash with present or future Standard Track
147 To reduce (but not eliminate) the potential for name clashes, the
148 convention is to prefix names of non-Standard Track with a few
149 letters to localize the changes to your organization. The smaller
150 the organization, the longer your prefix should be.
152 In the examples below, we have chosen a short prefix '{{EX:my}}'
153 (to save space). Such a short prefix would only be suitable for a
154 very large, global organization. In general, we recommend something
155 like '{{EX:deFirm}}' (German company) or '{{EX:comExample}}' (elements
156 associated with organization associated with {{EX:example.com}}).
159 H3: Local schema file
161 The {{EX:objectclass}} and {{EX:attributeTypes}} configuration file
162 directives can be used to define schema rules on entries in the
163 directory. It is customary to create a file to contain definitions
164 of your custom schema items. We recommend you create a file
165 {{F:local.schema}} in {{F:/usr/local/etc/openldap/schema/local.schema}}
166 and then include this file in your {{slapd.conf}}(5) file immediately
167 after other schema {{EX:include}} directives.
170 > include /usr/local/etc/openldap/schema/core.schema
171 > include /usr/local/etc/openldap/schema/cosine.schema
172 > include /usr/local/etc/openldap/schema/inetorgperson.schema
173 > # include local schema
174 > include /usr/local/etc/openldap/schema/local.schema
177 H3: Attribute Type Specification
179 The {{attributetype}} directive is used to define a new attribute
180 type. The directive uses the same Attribute Type Description
181 (as defined in {{REF:RFC2252}}) used by the attributeTypes
182 attribute found in the subschema subentry, e.g.:
184 E: attributetype <{{REF:RFC2252}} Attribute Type Description>
186 where Attribute Type Description is defined by the following
189 > AttributeTypeDescription = "(" whsp
190 > numericoid whsp ; AttributeType identifier
191 > [ "NAME" qdescrs ] ; name used in AttributeType
192 > [ "DESC" qdstring ] ; description
193 > [ "OBSOLETE" whsp ]
194 > [ "SUP" woid ] ; derived from this other
196 > [ "EQUALITY" woid ; Matching Rule name
197 > [ "ORDERING" woid ; Matching Rule name
198 > [ "SUBSTR" woid ] ; Matching Rule name
199 > [ "SYNTAX" whsp noidlen whsp ] ; Syntax OID
200 > [ "SINGLE-VALUE" whsp ] ; default multi-valued
201 > [ "COLLECTIVE" whsp ] ; default not collective
202 > [ "NO-USER-MODIFICATION" whsp ]; default user modifiable
203 > [ "USAGE" whsp AttributeUsage ]; default userApplications
207 > "userApplications" /
208 > "directoryOperation" /
209 > "distributedOperation" / ; DSA-shared
210 > "dSAOperation" ; DSA-specific, value depends on server
213 where whsp is a space ('{{EX: }}'), numericoid is a globally unique
214 OID in dotted-decimal form (e.g. {{EX:1.1.0}}), qdescrs is one or
215 more names, woid is either the name or OID optionally followed
216 by a length specifier (e.g {{EX:{10}}}).
218 For example, the attribute types {{EX:name}} and {{EX:cn}} are defined
219 in {{F:core.schema}} as:
221 > attributeType ( 2.5.4.41 NAME 'name'
222 > DESC 'name(s) associated with the object'
223 > EQUALITY caseIgnoreMatch
224 > SUBSTR caseIgnoreSubstringsMatch
225 > SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{32768} )
226 > attributeType ( 2.5.4.3 NAME ( 'cn' 'commonName' )
227 > DESC 'common name(s) assciated with the object'
230 Notice that each defines the attribute's OID, provides a short name,
231 and a brief description. Each name is an alias for the OID.
232 {{slapd}}(8) returns the first listed name when returning results.
234 The first attribute, {{EX:name}}, holds values of {{EX:directoryString}}
235 (UTF-8 encoded Unicode) syntax. The syntax is specified by OID
236 (1.3.6.1.4.1.1466.115.121.1.15 identifies the directoryString
237 syntax). A length recommendation of 32768 is specified. Servers
238 should support values of this length, but may support longer values
239 The field does NOT specify a size constraint, so is ignored on
240 servers (such as slapd) which don't impose such size limits. In
241 addition, the equality and substring matching uses case ignore
242 rules. Below are tables listing commonly used syntax and
243 matching rules (OpenLDAP supports these and many more).
245 !block table; align=Center; coltags="EX,EX,N"; \
246 title="Table 8.3: Commonly Used Syntaxes"
248 boolean 1.3.6.1.4.1.1466.115.121.1.7 boolean value
249 directoryString 1.3.6.1.4.1.1466.115.121.1.15 Unicode (UTF-8) string
250 distinguishedName 1.3.6.1.4.1.1466.115.121.1.12 LDAP DN
251 integer 1.3.6.1.4.1.1466.115.121.1.27 integer
252 numericString 1.3.6.1.4.1.1466.115.121.1.36 numeric string
253 OID 1.3.6.1.4.1.1466.115.121.1.38 object identifier
254 octetString 1.3.6.1.4.1.1466.115.121.1.40 arbitary octets
259 !block table; align=Center; coltags="EX,N"; \
260 title="Table 8.4: Commonly Used Matching Rules"
261 Name Type Description
262 booleanMatch equality boolean
263 caseIgnoreMatch equality case insensitive, space insensitive
264 caseIgnoreOrderingMatch ordering case insensitive, space insensitive
265 caseIgnoreSubstringsMatch substrings case insensitive, space insensitive
266 caseExactMatch equality case sensitive, space insensitive
267 caseExactOrderingMatch ordering case sensitive, space insensitive
268 caseExactSubstringsMatch substrings case sensitive, space insensitive
269 distinguishedNameMatch equality distinguished name
270 integerMatch equality integer
271 integerOrderingMatch ordering integer
272 numericStringMatch equality numerical
273 numericStringOrderingMatch ordering numerical
274 numericStringSubstringsMatch substrings numerical
275 octetStringMatch equality octet string
276 octetStringOrderingStringMatch ordering octet string
277 octetStringSubstringsStringMatch ordering octet string
278 objectIdentiferMatch equality object identifier
281 The second attribute, {{EX:cn}}, is a subtype of {{EX:name}} hence
282 it inherits the syntax, matching rules, and usage of {{EX:name}}.
283 {{EX:commonName}} is an alternative name.
285 Neither attribute is restricted to a single value. Both are meant
286 for usage by user applications. Neither is obsolete nor collective.
288 The following subsections provide a couple of examples.
293 Many organizations maintain a single unique name for each user.
294 Though one could use {{EX:displayName}} ({{REF:RFC2798}}), this
295 attribute is really meant to be controlled by the user, not the
296 organization. We could just copy the definition of {{EX:displayName}}
297 from {{F:inetorgperson.schema}} and replace the OID, name, and
300 > attributetype ( 1.1.2.1.1 NAME 'myUniqueName'
301 > DESC 'unique name with my organization'
302 > EQUALITY caseIgnoreMatch
303 > SUBSTR caseIgnoreSubstringsMatch
304 > SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
307 However, if we want this name to be included in
308 {{EX:name}} assertions [e.g. {{EX:(name=*Jane*)}}], the attribute
309 could alternatively be defined as a subtype of {{EX:name}}, e.g.:
311 > attributetype ( 1.1.2.1.1 NAME 'myUniqueName'
312 > DESC 'unique name with my organization'
318 Many organizations maintain a photo of each each user. A
319 {{EX:myPhoto}} attribute type could be defined to hold a photo.
320 Of course, one could use just use {{EX:jpegPhoto}} ({{REF:RFC2798}})
321 (or a subtype) to hold the photo. However, you can only do
322 this if the photo is in {{JPEG File Interchange Format}}.
323 Alternatively, an attribute type which uses the {{Octet String}}
324 syntax can be defined, e.g.:
326 > attributetype ( 1.1.2.1.2 NAME 'myPhoto'
327 > DESC 'a photo (application defined format)'
328 > SYNTAX 1.3.6.1.4.1.1466.115.121.1.40
331 In this case, the syntax doesn't specify the format of the photo.
332 It's assumed (maybe incorrectly) that all applications accessing
333 this attribute agree on the handling of values.
335 If you wanted to support multiple photo formats, you could define
336 a separate attribute type for each format, prefix the photo
337 with some typing information, or describe the value using
338 {{TERM:ASN.1}} and use the {{EX:;binary}} transfer option.
340 Another alternative is for the attribute to hold a {{TERM:URI}}
341 pointing to the photo. You can model such an attribute after
342 {{EX:labeledURI}} ({{REF:RFC2079}}) or simply create a subtype,
345 > attributetype ( 1.1.2.1.3 NAME 'myPhotoURI'
346 > DESC 'URI and optional label referring to a photo'
350 H3: Object Class Specification
352 The {{objectclasses}} directive is used to define a new object
353 class. The directive uses the same Object Class Description
354 (as defined in {{REF:RFC2252}}) used by the objectClasses
355 attribute found in the subschema subentry, e.g.:
357 E: objectclass <{{REF:RFC2252}} Object Class Description>
359 where Object Class Description is defined by the following
362 > ObjectClassDescription = "(" whsp
363 > numericoid whsp ; ObjectClass identifier
365 > [ "DESC" qdstring ]
366 > [ "OBSOLETE" whsp ]
367 > [ "SUP" oids ] ; Superior ObjectClasses
368 > [ ( "ABSTRACT" / "STRUCTURAL" / "AUXILIARY" ) whsp ]
369 > ; default structural
370 > [ "MUST" oids ] ; AttributeTypes
371 > [ "MAY" oids ] ; AttributeTypes
374 where whsp is a space ('{{EX: }}'), numericoid is a globally unique
375 OID in numeric form (e.g. {{EX:1.1.0}}), qdescrs is one or more
376 names, and oids is one or more names and/or OIDs.
381 To define an {{auxiliary}} object class which allows
382 myPhoto to be added to any existing entry.
384 > objectclass ( 1.1.2.2.1 NAME 'myPhotoObject'
385 > DESC 'mixin myPhoto'
392 If your organization would like have a private {{structural}}
393 object class to instantiate users, you can subclass one of
394 the existing person classes, such as {{EX:inetOrgPerson}}
395 ({{REF:RFC2798}}), and add any additional attributes which
398 > objectclass ( 1.1.2.2.2 NAME 'myPerson'
401 > MUST ( myUniqueName $ givenName )
404 The object class inherits the required/allowed attribute
405 types of {{EX:inetOrgPerson}} but requires {{EX:myUniqueName}}
406 and {{EX:givenName}} and allows {{EX:myPhoto}}.
409 H2: Transferring Schema
411 Since the {{slapd.conf}}(5) schema directives use {{REF:RFC2252}}
412 format values, you can extract schema elements published by
413 any LDAPv3 server and easily construct directives for use with
416 LDAPv3 servers publish schema elements in special {{subschema}}
417 entries (or subentries). While {{slapd}}(8) publishes a single
418 subschema subentry normally named {{EX:cn=Subschema}}, this behavior
419 cannot be expected from other servers. The subschema subentry
420 controlling a particular entry can be obtained by examining the
421 {{EX:subschemaSubentry}} attribute contained in the entry at the
422 root of each administrative context. For example,
424 > ldapsearch -LLL -x -b "dc=example,dc=com" -s base "(objectclass=*)" subschemaSubentry
426 To obtain the schema from a subschema subentry, you can use
427 ldapsearch(1) as follows (replace the search base as needed):
429 > ldapsearch -LLL -x -b "cn=Subschema" -s base "(objectclass=subschema)" attributeTypes objectClasses
431 where "cn=Subschema" is the value of subschemaSubentry returned in
434 This will return {{TERM:LDIF}} output containing many type/value
435 pairs. The following is an abbreviated example:
438 > objectClasses: ( 1.1.2.2.2 NAME 'myPerson' DESC 'my person' SUP inet
439 > OrgPerson MUST ( myUniqueName $ givenName ) MAY myPhoto )
440 > attributeTypes: ( 1.1.2.1.1 NAME 'myUniqueName' DESC 'unique name wi
441 > th my organization' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubst
442 > ringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE )
443 > attributeTypes: ( 1.1.2.1.2 NAME 'myPhoto' DESC 'a photo (applicatio
444 > n defined format)' SYNTAX 1.3.6.1.4.1.1466.115.121.1.40
446 Capture the output of the search in a file and then edit the file:
448 + to contain only desired type/value pairs
449 ^ join LDIF continuation lines
450 ^ replace attribute type with directive name
451 (e.g. {{EX:s/attributeTypes:/attributeType /}} and
452 {{EX:s/objectClasses:/objectClass /}}).
453 ^ reorder lines so each element is defined before first use
454 ^ continue long directives over multiple lines
456 For the three type/value pairs in our example, the edit should
457 result in a file with contains of:
459 > attributetype ( 1.1.2.1.1 NAME 'myUniqueName'
460 > DESC 'unique name with my organization'
461 > EQUALITY caseIgnoreMatch
462 > SUBSTR caseIgnoreSubstringsMatch
463 > SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
465 > attributeType ( 1.1.2.1.2 NAME 'myPhoto'
466 > DESC 'a photo (application defined format)'
467 > SYNTAX 1.3.6.1.4.1.1466.115.121.1.40
468 > objectClass ( 1.1.2.2.2 NAME 'myPerson'
471 > MUST ( myUniqueName $ givenName )
474 Save in an appropriately named file (e.g. {{F:local.schema}}).
475 You may now include this file in your {{slapd.conf}}(5) file.
481 To ease the management and use of OIDs, {{slapd}}(8) supports
482 {{Object Identifier}} macros. The {{EX:objectIdentifier}} directive
483 is used to equate a macro (name) with a OID. The OID may possibly
484 be derived from a previously defined OID macro. The {{slapd.conf}}(5)
487 E: objectIdentifier <name> { <oid> | <name>[:<suffix>] }
489 The following demonstrates definition of a set of OID macros
490 and their use in defining schema elements:
492 > objectIdentifier myOID 1.1
493 > objectIdentifier mySNMP myOID:1
494 > objectIdentifier myLDAP myOID:2
495 > objectIdentifier myAttributeType myLDAP:1
496 > objectIdentifier myObjectClass myLDAP:2
497 > attributetype ( myAttributeType:3 NAME 'myPhotoURI'
498 > DESC 'URI and optional label referring to a photo'
500 > objectclass ( myObjectClass:1 NAME 'myPhotoObject'
501 > DESC 'mixin myPhoto'