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 details optional schema definitions provided
9 in the distribution and where to obtain other definitions. The
10 second section details how to define new schema items.
12 H2: Distributed Schema Files
14 OpenLDAP is distributed with a set of schema specifications for
15 your use. Each set is defined in a file suitable for inclusion
16 (using the {{EX:include}} directive) in your {{slapd.conf}}(5)
17 file. These schema files are normally installed in the
18 {{F:/usr/local/etc/openldap/schema}} directory.
20 !block table; colaligns="LR"; coltags="F,N"; align=Center; \
21 title="Table 6.1: Provided Schema Specifications"
23 core.schema OpenLDAP {{core}} (required)
24 cosine.schema Cosine and Internet X.500 (useful)
25 inetorgperson.schema InetOrgPerson (useful)
26 misc.schema Assorted (experimental)
27 nadf.schema North American Directory Forum (FYI)
28 nis.schema Network Information Services (FYI)
29 openldap.schema OpenLDAP Project (experimental)
32 To use any of these schema files, you only need to include the
33 the desired file in the global definitions portion of your
34 {{slapd.conf}}(5) file. For example:
37 > include /usr/local/etc/openldap/schema/core.schema
38 > include /usr/local/etc/openldap/schema/cosine.schema
39 > include /usr/local/etc/openldap/schema/inetorgperson.schema
41 Additional files may be available. Please consult the OpenLDAP
42 FAQ ({{URL:http://www.openldap.org/faq/}}).
44 Note: You should not modify any of the schema items defined
49 Schema used by {{slapd}}(8) may be extended to support additional
50 syntaxes, matching rules, attribute types, and object classes.
51 This chapter details how to add attribute types and object classes
52 using the syntaxes and matching rules already support by slapd.
53 slapd can also be extended to support additional syntaxes
54 and matching rules, but this requires some programming and hence
55 is not discussed here.
57 There are five steps to defining new schema:
58 ^ obtain Object Identifer
59 + choose a name prefix
60 + create local schema file
61 + define custom attribute types (if necessary)
62 + define custom object classes
64 H3: Object Identifiers
66 Each schema element is identified by a globally unique
67 {{TERM[expand]OID}} (OID). OIDs are also used to identify
69 They are commonly found in protocols described by {{TERM:ASN.1}}. In
70 particular, they are heavy used by {{TERM[expand]SNMP}} (SNMP).
71 As OIDs are hierarchical, your organization
72 can obtain one OID and branch it as needed. For example,
73 if your organization were assigned OID {{EX:1.1}}, you could branch
76 !block table; colaligns="LR"; coltags="EX,N"; align=Center; \
77 title="Table 6.2: Example OID hierarchy"
79 1.1 Organization's OID
82 1.1.2.1 AttributeTypes
85 1.1.2.2.1 myObjectClass
88 You are, of course, free to design a hierarchy suitable to your
89 organizational needs under your organization's OID. No matter
90 what hierarchy you choose, you should maintain a registry of
91 assignments you make. This can be a simple flat file or a
92 something more sophisticated such as the {{OpenLDAP OID Registry}}
93 ({{URL:http://www.openldap.org/faq/index.cgi?file=197}}).
95 For more information about Object Identifers (and a listing
96 service) see {{URL:http://www.alvestrand.no/harald/objectid/}}.
98 .{{Under no circumstances should you use a fictious OID!}}
100 To obtain a fully registered OID at {{no cost}}, apply for
101 a OID under {{ORG[expand]IANA}} (IANA) maintained
102 {{Private Enterprise}} arch. Any private enterprise (organization)
103 may request an OID to be assigned under this arch. Just fill
104 out the {{ORG:IANA}} form at {{URL: http://www.iana.org/cgi-bin/enterprise.pl}}
105 and your official OID will be sent to you usually within a few days.
106 Your base OID will be something like {{EX:1.3.6.1.4.1.X}} were {{EX:X}}
109 Note: Don't let the "MIB/SNMP" statement on the IANA page confuse you.
110 OIDs obtained using this form may be used for any purpose including
111 identifying LDAP schema elements.
116 In addition to assign a unique object identifier to each schema
117 element, you should provide a least one textual name for each
118 element. The name should be both descriptive and no likely
119 to clash with names of other schema elements. In particular,
120 any name you choose should not clash with present or future
121 Standard Track names.
123 To reduce (but not eliminate) the potential for name clashes,
124 the convention is to prefix names of non-Standard Track with
125 a few letters to localize the changes to your organization.
126 The smaller the organization, the longer your prefix should
129 In the examples below, we have choosen a short prefix '{{EX:my}}'
130 (to save space). Such a short would only be suitable for a
131 very large, global organization. For a small, local
132 organization, we recommend something like '{{EX:deFirm}}'
133 (German company) or '{{EX:comExample}}' (elements associated
134 with organization associated with {{EX:example.com}}).
137 H3: Local schema file
139 The {{EX:objectclass}} and {{EX:attributeTypes}} configuration file
140 directives can be used to define schema rules on entries in the
141 directory. It is customary to create a file to contain definitions
142 of your custom schema items. We recommend you create a file
143 {{F:local.schema}} in {{F:/usr/local/etc/openldap/schema/local.schema}}
144 and then include this file in your {{slapd.conf}}(5) file immediately
145 after other schema {{EX:include}} directives.
148 > include /usr/local/etc/openldap/schema/core.schema
149 > include /usr/local/etc/openldap/schema/cosine.schema
150 > include /usr/local/etc/openldap/schema/inetorgperson.schema
151 > # include local schema
152 > include /usr/local/etc/openldap/schema/local.schema
155 H3: Attribute Type Specification
157 The {{attributetype}} directive is used to define a new attribute
158 type. The directive uses the same Attribute Type Description
159 (as defined in {{REF:RFC2252}}) used by the attributeTypes
160 attribute found in the subschema subentry, e.g.:
162 E: attributetype <{{REF:RFC2252}} Attribute Type Description>
164 where Attribute Type Description is defined by the following
167 > AttributeTypeDescription = "(" whsp
168 > numericoid whsp ; AttributeType identifier
169 > [ "NAME" qdescrs ] ; name used in AttributeType
170 > [ "DESC" qdstring ] ; description
171 > [ "OBSOLETE" whsp ]
172 > [ "SUP" woid ] ; derived from this other
174 > [ "EQUALITY" woid ; Matching Rule name
175 > [ "ORDERING" woid ; Matching Rule name
176 > [ "SUBSTR" woid ] ; Matching Rule name
177 > [ "SYNTAX" whsp noidlen whsp ] ; see section 4.3
178 > [ "SINGLE-VALUE" whsp ] ; default multi-valued
179 > [ "COLLECTIVE" whsp ] ; default not collective
180 > [ "NO-USER-MODIFICATION" whsp ]; default user modifiable
181 > [ "USAGE" whsp AttributeUsage ]; default userApplications
185 > "userApplications" /
186 > "directoryOperation" /
187 > "distributedOperation" / ; DSA-shared
188 > "dSAOperation" ; DSA-specific, value depends on server
191 where whsp is a space ('{{EX: }}'), numericoid is a globally unique
192 OID in numeric form (e.g. {{EX:1.2.3}}), qdescrs is one or more
193 names, woid is either the name or OID, and noidlen is a optional length
194 specifier (e.g {{EX:{10}}}).
196 For example, the attribute types {{EX:name}} and {{EX:cn}} are defined
197 in {{F:core.schema}} as:
199 > attributeType: ( 2.5.4.41 NAME 'name'
200 > EQUALITY caseIgnoreMatch
201 > SUBSTR caseIgnoreSubstringsMatch
202 > SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{32768} )
203 > attributeType: ( 2.5.4.3 NAME
204 > ( 'cn' $ 'commonName' ) SUP name )
206 Notice that each defines the attribute's OID and descriptive
207 names. Each name is an alias for the OID. {{slapd}}(8) returns
208 the first listed name when returning results.
210 The first attribute, {{EX:name}}, has a syntax of directory string
211 (a UTF-8 encoded Unicode string) with a recommend maximun length.
212 Note that syntaxes is specified by OID. In addition, the equality
213 and substring matching uses case ignore rules. Below are tables
214 listing commonly used supported syntax and matching rules.
216 !block table; align=Center; coltags="EX,EX,N"; \
217 title="Table 6.3: Supported Syntaxes"
219 binary 1.3.6.1.4.1.1466.115.121.1.5 BER/DER data
220 boolean 1.3.6.1.4.1.1466.115.121.1.7 boolean value
221 distinguishedName 1.3.6.1.4.1.1466.115.121.1.15 DN
222 directoryString 1.3.6.1.4.1.1466.115.121.1.15 UTF-8 string
223 IA5String 1.3.6.1.4.1.1466.115.121.1.26 ASCII string
224 Integer 1.3.6.1.4.1.1466.115.121.1.27 integer
225 Name and Optional UID 1.3.6.1.4.1.1466.115.121.1.34 DN plus UID
226 Numeric String 1.3.6.1.4.1.1466.115.121.1.36 numeric string
227 OID 1.3.6.1.4.1.1466.115.121.1.38 object identifier
228 Octet String 1.3.6.1.4.1.1466.115.121.1.40 arbitary octets
229 Printable String 1.3.6.1.4.1.1466.115.121.1.44 printable string
234 !block table; align=Center; coltags="EX,N"; \
235 title="Table 6.4: Supported Matching Rules"
236 Name Type Description
237 booleanMatch equality boolean
238 objectIdentiferMatch equality OID
239 distinguishedNameMatch equality DN
240 uniqueMemberMatch equality DN with optional UID
241 numericStringMatch equality numerical
242 numericStringOrderingMatch ordering numerical
243 numericStringSubstringsMatch substrings numerical
244 caseIgnoreMatch equality case insensitive, space insensitive
245 caseIgnoreOrderingMatch ordering case insensitive, space insensitive
246 caseIgnoreSubstringsMatch substrings case insensitive, space insensitive
247 caseExactMatch equality case sensitive, space insensitive
248 caseExactOrderingMatch ordering case sensitive, space insensitive
249 caseExactSubstringsMatch substrings case sensitive, space insensitive
250 caseIgnoreIA5Match equality case insensitive, space insensitive
251 caseIgnoreOrderingIA5Match ordering case insensitive, space insensitive
252 caseIgnoreSubstringsIA5Match substrings case insensitive, space insensitive
253 caseExactIA5Match equality case sensitive, space insensitive
254 caseExactOrderingIA5Match ordering case sensitive, space insensitive
255 caseExactSubstringsIA5Match substrings case sensitive, space insensitive
258 The second attribute, {{EX:cn}}, is a subtype of {{EX:name}} hence
259 in inherits the syntax, matching rules, and usage of {{EX:name}}.
260 {{EX:commonName}} is an alternative name.
262 Neither attributes is restricted to a single value and both are
263 meant for usage by user applications. You likely won't need to
264 specify other parameters such as {{EX:OBSOLETE}}.
266 The following subsections provide a couple of examples.
271 Many organizations maintain a single unique name for each user.
272 Though one could use {{EX:displayName}} ({{REF:RFC2798}}), but this
273 attribute is meant to be controlled by the user, not the
274 organization. We could just copy the definition of {{EX:displayName}}
275 from {{F:inetorgperson.schema}} and replace the OID, name, and
278 > attributetype ( 1.1.2.1.1 NAME 'myUniqueName'
279 > DESC 'unique name with my organization'
280 > EQUALITY caseIgnoreMatch
281 > SUBSTR caseIgnoreSubstringsMatch
282 > SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
285 However, if we desire this name to included in
286 {{EX:name}} assertions [e.g. {{EX:(name=*Jane*)}}], the attribute
287 could alternatively be defined as a subtype of {{EX:name}}, e.g.:
289 > attributetype ( 1.1.2.1.1 NAME 'myUniqueName'
290 > DESC 'unique name with my organization'
296 Many organizations maintain a photo of each each user. A
297 {{EX:myPhoto}} attribute type could be defined to hold a photo.
298 Of course, one could use just use {{EX:jpegPhoto}} ({{REF:RFC2798}})
299 (or a subtype) to hold the photo. However, you can only do
300 this if the photo is in {{JPEG File Interchange Format}}.
301 Alternatively, an attribute type which uses the {{Octet String}}
302 syntax can be defined, e.g.:
304 > attributetype ( 1.1.2.1.2 NAME 'myPhoto'
305 > DESC 'a photo (application defined format)'
306 > SYNTAX 1.3.6.1.4.1.1466.115.121.1.40
309 As noted in the description, LDAP has no knowledge of the
310 format of the photo. It's assumed that all applications
311 accessing this attribute agree on the handling of values.
313 If you want to support multiple photo format, one could define
314 a separate attributes type for each format, prefix the photo
315 with some typing information, or describe the value using
316 {{TERM:ASN.1}} and use the {{EX:;binary}} transfer option.
318 Another alternative is for the attribute to hold a {{TERM:URI}}
319 pointing to the photo. You can model such an attribute after
320 {{EX:labeledURI}} ({{REF:RFC2079}}).
323 H3: Object Class Specification
325 The {{objectclasses}} directive is used to define a new object
326 class. The directive uses the same Object Class Description
327 (as defined in {{REF:RFC2252}}) used by the objectClasses
328 attribute found in the subschema subentry, e.g.:
330 E: objectclass <{{REF:RFC2252}} Object Class Description>
332 where Object Class Description is defined by the following
335 > ObjectClassDescription = "(" whsp
336 > numericoid whsp ; ObjectClass identifier
338 > [ "DESC" qdstring ]
339 > [ "OBSOLETE" whsp ]
340 > [ "SUP" oids ] ; Superior ObjectClasses
341 > [ ( "ABSTRACT" / "STRUCTURAL" / "AUXILIARY" ) whsp ]
342 > ; default structural
343 > [ "MUST" oids ] ; AttributeTypes
344 > [ "MAY" oids ] ; AttributeTypes
347 where whsp is a space ('{{EX: }}'), numericoid is a globally unique
348 OID in numeric form (e.g. {{EX:1.2.3}}), qdescrs is one or more
349 names, oids is one or more names and/or OIDs.
354 To define an {{auxiliary}} object class which allows
355 myPhoto to be added to any existing entry.
357 > objectclass ( 1.1.2.2.1 NAME 'myPhotoObject'
358 > DESC 'mixin myPhoto'
365 If your organization would like have a private {{structural}}
366 object class to instantiate users, you can subclass one of
367 the existing person classes, such as {{EX:inetOrgPerson}}
368 ({{REF:RFC2798}}), and add any additional attributes which
371 > objectclass ( 1.1.2.2.2 NAME 'myPerson'
373 > MUST ( 'myUniqueName' $ 'givenName' )
377 The object class inherits the required/allowed attribute
378 types of {{EX:inetOrgPerson}} but requires {{EX:myUniqueName}}
379 and {{EX:givenName}} and allows {{EX:myPhoto}}.