2 # Copyright 1999-2000, The OpenLDAP Foundation, All Rights Reserved.
3 # COPYING RESTRICTIONS APPLY, see COPYRIGHT.
5 H1: Schema Specification
7 This chapter describes how to extend the schema used by {{slapd}}(8).
8 The first section, {{SECT:Distributed Schema Files}} details optional
9 schema definitions provided in the distribution and where to obtain
11 The second section, {{SECT:Extending Schema}}, details how to define
14 The third section, {{SECT:Transferring Schema}} details how you can
15 export schema definitions from an LDAPv3 server and transform it
16 to {{slapd.conf}}(5) format.
19 H2: Distributed Schema Files
21 OpenLDAP is distributed with a set of schema specifications for
22 your use. Each set is defined in a file suitable for inclusion
23 (using the {{EX:include}} directive) in your {{slapd.conf}}(5)
24 file. These schema files are normally installed in the
25 {{F:/usr/local/etc/openldap/schema}} directory.
27 !block table; colaligns="LR"; coltags="F,N"; align=Center; \
28 title="Table 6.1: Provided Schema Specifications"
30 core.schema OpenLDAP {{core}} (required)
31 cosine.schema Cosine and Internet X.500 (useful)
32 inetorgperson.schema InetOrgPerson (useful)
33 misc.schema Assorted (experimental)
34 nadf.schema North American Directory Forum (FYI)
35 nis.schema Network Information Services (FYI)
36 openldap.schema OpenLDAP Project (experimental)
39 To use any of these schema files, you only need to include the
40 the desired file in the global definitions portion of your
41 {{slapd.conf}}(5) file. For example:
44 > include /usr/local/etc/openldap/schema/core.schema
45 > include /usr/local/etc/openldap/schema/cosine.schema
46 > include /usr/local/etc/openldap/schema/inetorgperson.schema
48 Additional files may be available. Please consult the OpenLDAP
49 FAQ ({{URL:http://www.openldap.org/faq/}}).
51 Note: You should not modify any of the schema items defined
56 Schema used by {{slapd}}(8) may be extended to support additional
57 syntaxes, matching rules, attribute types, and object classes.
58 This chapter details how to add attribute types and object classes
59 using the syntaxes and matching rules already supported by slapd.
60 slapd can also be extended to support additional syntaxes
61 and matching rules, but this requires some programming and hence
62 is not discussed here.
64 There are five steps to defining new schema:
65 ^ obtain Object Identifer
66 + choose a name prefix
67 + create local schema file
68 + define custom attribute types (if necessary)
69 + define custom object classes
71 H3: Object Identifiers
73 Each schema element is identified by a globally unique
74 {{TERM[expand]OID}} (OID). OIDs are also used to identify
76 They are commonly found in protocols described by {{TERM:ASN.1}}. In
77 particular, they are heavily used by the {{TERM[expand]SNMP}} (SNMP).
78 As OIDs are hierarchical, your organization
79 can obtain one OID and branch it as needed. For example,
80 if your organization were assigned OID {{EX:1.1}}, you could branch
83 !block table; colaligns="LR"; coltags="EX,N"; align=Center; \
84 title="Table 6.2: Example OID hierarchy"
86 1.1 Organization's OID
89 1.1.2.1 AttributeTypes
92 1.1.2.2.1 myObjectClass
95 You are, of course, free to design a hierarchy suitable to your
96 organizational needs under your organization's OID. No matter
97 what hierarchy you choose, you should maintain a registry of
98 assignments you make. This can be a simple flat file or a
99 something more sophisticated such as the {{OpenLDAP OID Registry}}
100 ({{URL:http://www.openldap.org/faq/index.cgi?file=197}}).
102 For more information about Object Identifers (and a listing
103 service) see {{URL:http://www.alvestrand.no/harald/objectid/}}.
105 .{{Under no circumstances should you use a fictious OID!}}
107 To obtain a fully registered OID at {{no cost}}, apply for
108 an OID under {{ORG[expand]IANA}} (IANA) maintained
109 {{Private Enterprise}} arch. Any private enterprise (organization)
110 may request an OID to be assigned under this arch. Just fill
111 out the {{ORG:IANA}} form at {{URL: http://www.iana.org/cgi-bin/enterprise.pl}}
112 and your official OID will be sent to you usually within a few days.
113 Your base OID will be something like {{EX:1.3.6.1.4.1.X}} were {{EX:X}}
116 Note: Don't let the "MIB/SNMP" statement on the IANA page confuse you.
117 OIDs obtained using this form may be used for any purpose including
118 identifying LDAP schema elements.
123 In addition to assigning a unique object identifier to each schema
124 element, you should provide a least one textual name for each
125 element. The name should be both descriptive and not likely
126 to clash with names of other schema elements. In particular,
127 any name you choose should not clash with present or future
128 Standard Track names.
130 To reduce (but not eliminate) the potential for name clashes,
131 the convention is to prefix names of non-Standard Track with
132 a few letters to localize the changes to your organization.
133 The smaller the organization, the longer your prefix should
136 In the examples below, we have choosen a short prefix '{{EX:my}}'
137 (to save space). Such a short prefix would only be suitable for
138 a very large, global organization. For a small, local organization,
139 we recommend something like '{{EX:deFirm}}' (German company) or
140 '{{EX:comExample}}' (elements associated with organization associated
141 with {{EX:example.com}}).
144 H3: Local schema file
146 The {{EX:objectclass}} and {{EX:attributeTypes}} configuration file
147 directives can be used to define schema rules on entries in the
148 directory. It is customary to create a file to contain definitions
149 of your custom schema items. We recommend you create a file
150 {{F:local.schema}} in {{F:/usr/local/etc/openldap/schema/local.schema}}
151 and then include this file in your {{slapd.conf}}(5) file immediately
152 after other schema {{EX:include}} directives.
155 > include /usr/local/etc/openldap/schema/core.schema
156 > include /usr/local/etc/openldap/schema/cosine.schema
157 > include /usr/local/etc/openldap/schema/inetorgperson.schema
158 > # include local schema
159 > include /usr/local/etc/openldap/schema/local.schema
162 H3: Attribute Type Specification
164 The {{attributetype}} directive is used to define a new attribute
165 type. The directive uses the same Attribute Type Description
166 (as defined in {{REF:RFC2252}}) used by the attributeTypes
167 attribute found in the subschema subentry, e.g.:
169 E: attributetype <{{REF:RFC2252}} Attribute Type Description>
171 where Attribute Type Description is defined by the following
174 > AttributeTypeDescription = "(" whsp
175 > numericoid whsp ; AttributeType identifier
176 > [ "NAME" qdescrs ] ; name used in AttributeType
177 > [ "DESC" qdstring ] ; description
178 > [ "OBSOLETE" whsp ]
179 > [ "SUP" woid ] ; derived from this other
181 > [ "EQUALITY" woid ; Matching Rule name
182 > [ "ORDERING" woid ; Matching Rule name
183 > [ "SUBSTR" woid ] ; Matching Rule name
184 > [ "SYNTAX" whsp noidlen whsp ] ; see section 4.3
185 > [ "SINGLE-VALUE" whsp ] ; default multi-valued
186 > [ "COLLECTIVE" whsp ] ; default not collective
187 > [ "NO-USER-MODIFICATION" whsp ]; default user modifiable
188 > [ "USAGE" whsp AttributeUsage ]; default userApplications
192 > "userApplications" /
193 > "directoryOperation" /
194 > "distributedOperation" / ; DSA-shared
195 > "dSAOperation" ; DSA-specific, value depends on server
198 where whsp is a space ('{{EX: }}'), numericoid is a globally unique
199 OID in dotted-decimal form (e.g. {{EX:1.2.3}}), qdescrs is one or more
200 names, woid is either the name or OID, and noidlen is an optional length
201 specifier (e.g {{EX:{10}}}).
203 For example, the attribute types {{EX:name}} and {{EX:cn}} are defined
204 in {{F:core.schema}} as:
206 > attributeType ( 2.5.4.41 NAME 'name'
207 > EQUALITY caseIgnoreMatch
208 > SUBSTR caseIgnoreSubstringsMatch
209 > SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{32768} )
210 > attributeType ( 2.5.4.3 NAME
211 > ( 'cn' $ 'commonName' ) SUP name )
213 Notice that each defines the attribute's OID and descriptive
214 names. Each name is an alias for the OID. {{slapd}}(8) returns
215 the first listed name when returning results.
217 The first attribute, {{EX:name}}, has a syntax of {{EX:directoryString}}
218 (a UTF-8 encoded Unicode string) with a recommend maximun length.
219 Note that syntaxes are specified by OID. In addition, the equality
220 and substring matching uses case ignore rules. Below are tables
221 listing commonly used supported syntax and matching rules.
223 !block table; align=Center; coltags="EX,EX,N"; \
224 title="Table 6.3: Supported Syntaxes"
226 binary 1.3.6.1.4.1.1466.115.121.1.5 BER/DER data
227 boolean 1.3.6.1.4.1.1466.115.121.1.7 boolean value
228 distinguishedName 1.3.6.1.4.1.1466.115.121.1.12 DN
229 directoryString 1.3.6.1.4.1.1466.115.121.1.15 UTF-8 string
230 IA5String 1.3.6.1.4.1.1466.115.121.1.26 ASCII string
231 Integer 1.3.6.1.4.1.1466.115.121.1.27 integer
232 Name and Optional UID 1.3.6.1.4.1.1466.115.121.1.34 DN plus UID
233 Numeric String 1.3.6.1.4.1.1466.115.121.1.36 numeric string
234 OID 1.3.6.1.4.1.1466.115.121.1.38 object identifier
235 Octet String 1.3.6.1.4.1.1466.115.121.1.40 arbitary octets
236 Printable String 1.3.6.1.4.1.1466.115.121.1.44 printable string
241 !block table; align=Center; coltags="EX,N"; \
242 title="Table 6.4: Supported Matching Rules"
243 Name Type Description
244 booleanMatch equality boolean
245 objectIdentiferMatch equality OID
246 distinguishedNameMatch equality DN
247 uniqueMemberMatch equality DN with optional UID
248 numericStringMatch equality numerical
249 numericStringOrderingMatch ordering numerical
250 numericStringSubstringsMatch substrings numerical
251 caseIgnoreMatch equality case insensitive, space insensitive
252 caseIgnoreOrderingMatch ordering case insensitive, space insensitive
253 caseIgnoreSubstringsMatch substrings case insensitive, space insensitive
254 caseExactMatch equality case sensitive, space insensitive
255 caseExactOrderingMatch ordering case sensitive, space insensitive
256 caseExactSubstringsMatch substrings case sensitive, space insensitive
257 caseIgnoreIA5Match equality case insensitive, space insensitive
258 caseIgnoreIA5OrderingMatch ordering case insensitive, space insensitive
259 caseIgnoreIA5SubstringsMatch substrings case insensitive, space insensitive
260 caseExactIA5Match equality case sensitive, space insensitive
261 caseExactIA5OrderingMatch ordering case sensitive, space insensitive
262 caseExactIA5SubstringsMatch substrings case sensitive, space insensitive
265 The second attribute, {{EX:cn}}, is a subtype of {{EX:name}} hence
266 it inherits the syntax, matching rules, and usage of {{EX:name}}.
267 {{EX:commonName}} is an alternative name.
269 Neither attribute is restricted to a single value and both are
270 meant for usage by user applications. You likely won't need to
271 specify other parameters such as {{EX:OBSOLETE}}.
273 The following subsections provide a couple of examples.
278 Many organizations maintain a single unique name for each user.
279 Though one could use {{EX:displayName}} ({{REF:RFC2798}}), this
280 attribute is really meant to be controlled by the user, not the
281 organization. We could just copy the definition of {{EX:displayName}}
282 from {{F:inetorgperson.schema}} and replace the OID, name, and
285 > attributetype ( 1.1.2.1.1 NAME 'myUniqueName'
286 > DESC 'unique name with my organization'
287 > EQUALITY caseIgnoreMatch
288 > SUBSTR caseIgnoreSubstringsMatch
289 > SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
292 However, if we want this name to be included in
293 {{EX:name}} assertions [e.g. {{EX:(name=*Jane*)}}], the attribute
294 could alternatively be defined as a subtype of {{EX:name}}, e.g.:
296 > attributetype ( 1.1.2.1.1 NAME 'myUniqueName'
297 > DESC 'unique name with my organization'
303 Many organizations maintain a photo of each each user. A
304 {{EX:myPhoto}} attribute type could be defined to hold a photo.
305 Of course, one could use just use {{EX:jpegPhoto}} ({{REF:RFC2798}})
306 (or a subtype) to hold the photo. However, you can only do
307 this if the photo is in {{JPEG File Interchange Format}}.
308 Alternatively, an attribute type which uses the {{Octet String}}
309 syntax can be defined, e.g.:
311 > attributetype ( 1.1.2.1.2 NAME 'myPhoto'
312 > DESC 'a photo (application defined format)'
313 > SYNTAX 1.3.6.1.4.1.1466.115.121.1.40
316 As noted in the description, LDAP has no knowledge of the
317 format of the photo. It's assumed that all applications
318 accessing this attribute agree on the handling of values.
320 If you wanted to support multiple photo formats, you could define
321 a separate attribute type for each format, prefix the photo
322 with some typing information, or describe the value using
323 {{TERM:ASN.1}} and use the {{EX:;binary}} transfer option.
325 Another alternative is for the attribute to hold a {{TERM:URI}}
326 pointing to the photo. You can model such an attribute after
327 {{EX:labeledURI}} ({{REF:RFC2079}}).
330 H3: Object Class Specification
332 The {{objectclasses}} directive is used to define a new object
333 class. The directive uses the same Object Class Description
334 (as defined in {{REF:RFC2252}}) used by the objectClasses
335 attribute found in the subschema subentry, e.g.:
337 E: objectclass <{{REF:RFC2252}} Object Class Description>
339 where Object Class Description is defined by the following
342 > ObjectClassDescription = "(" whsp
343 > numericoid whsp ; ObjectClass identifier
345 > [ "DESC" qdstring ]
346 > [ "OBSOLETE" whsp ]
347 > [ "SUP" oids ] ; Superior ObjectClasses
348 > [ ( "ABSTRACT" / "STRUCTURAL" / "AUXILIARY" ) whsp ]
349 > ; default structural
350 > [ "MUST" oids ] ; AttributeTypes
351 > [ "MAY" oids ] ; AttributeTypes
354 where whsp is a space ('{{EX: }}'), numericoid is a globally unique
355 OID in numeric form (e.g. {{EX:1.2.3}}), qdescrs is one or more
356 names, and oids is one or more names and/or OIDs.
361 To define an {{auxiliary}} object class which allows
362 myPhoto to be added to any existing entry.
364 > objectclass ( 1.1.2.2.1 NAME 'myPhotoObject'
365 > DESC 'mixin myPhoto'
372 If your organization would like have a private {{structural}}
373 object class to instantiate users, you can subclass one of
374 the existing person classes, such as {{EX:inetOrgPerson}}
375 ({{REF:RFC2798}}), and add any additional attributes which
378 > objectclass ( 1.1.2.2.2 NAME 'myPerson'
381 > MUST ( 'myUniqueName' $ 'givenName' )
384 The object class inherits the required/allowed attribute
385 types of {{EX:inetOrgPerson}} but requires {{EX:myUniqueName}}
386 and {{EX:givenName}} and allows {{EX:myPhoto}}.
389 H2: Transferring Schema
391 Since the {{slapd.conf}}(5) schema directives use {{REF:RFC2252}}
392 format values, you can extract schema elements published by
393 any LDAPv3 server and easily construct directives for use with
396 LDAPv3 servers publish schema elements in special {{subschema}}
397 entries (or subentries). {{slapd}}(8) publishes a single subschema
398 entry normally named {{EX:cn=Subschema}}. If a server which
399 supports a single subschema subentry, the DN of the subschema
400 subenty can usually be found by examining the value of the
401 {{EX:subschemaSubentry}} attribute type in the {{root DSE}}
402 Other servers may publish multiple subschema entries. These
403 can be located by examining the {{EX:subschemaSubentry}} attribute
404 contained in the entry at the root of each administrative context.
406 To obtain the schema from a subschema subentry, you can use
407 ldapsearch(1) as follows (replace the search base as needed):
409 > ldapsearch -LLL -x -b "cn=Subschema" -s base "(objectclass=subschema)" attributeTypes objectClasses
411 This will return {{TERM:LDIF}} output containing many type/value
412 pairs. The following is an abbreviated example:
415 > attributeTypes: ( 1.1.2.1.1 NAME 'myUniqueName' DESC 'unique name wi
416 > th my organization' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubst
417 > ringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE )
418 > attributeTypes: ( 1.1.2.1.2 NAME 'myPhoto' DESC 'a photo (applicatio
419 > n defined format)' SYNTAX 1.3.6.1.4.1.1466.115.121.1.40
420 > objectClasses: ( 1.1.2.2.2 NAME 'myPerson' DESC 'my person' SUP inet
421 > OrgPerson MUST ( 'myUniqueName' $ 'givenName' ) MAY 'myPhoto' )
423 Capture the output of the search in a file and then edit the file:
425 + to contain only desired type/value pairs
426 ^ join LDIF continuation lines
427 ^ replace attribute type with directive name
428 (e.g. {{EX:s/attributeTypes:/attributeType/}} and
429 {{EX:s/objectClasses:/objectClass/}}).
430 ^ continue long directives over multiple lines
432 For the three type/value pairs in our example, the edit should
433 result in a file with contains of:
435 > attributetype ( 1.1.2.1.1 NAME 'myUniqueName'
436 > DESC 'unique name with my organization'
437 > EQUALITY caseIgnoreMatch
438 > SUBSTR caseIgnoreSubstringsMatch
439 > SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
441 > attributeType ( 1.1.2.1.2 NAME 'myPhoto'
442 > DESC 'a photo (application defined format)'
443 > SYNTAX 1.3.6.1.4.1.1466.115.121.1.40
444 > objectClass ( 1.1.2.2.2 NAME 'myPerson'
447 > MUST ( 'myUniqueName' $ 'givenName' )
450 Save in an appropriately named file (e.g. {{F:my.schema}}).
451 You may now include this file in your {{slapd.conf}}(8) file.