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 {{slapd}}(8) schema. The
8 first section details how to extend schema using provided
9 schema files. The second section details how to define
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"; align=Center; \
21 title="Table 6.1: Provided Schema Specifications"
23 {{F:core.schema}} OpenLDAP {{core}} (required)
24 {{F:cosine.schema}} Cosine and Internet X.500 (useful)
25 {{F:inetorgperson.schema}} InetOrgPerson (useful)
26 {{F:misc.schema}} Assorted (experimental)
27 {{F:nadf.schema}} North American Directory Forum (FYI)
28 {{F:nis.schema}} Network Information Services (FYI)
29 {{F: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) can 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(8) 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 naming 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}} ({{TERM: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 {{Simple Network Management
71 Protocol}} (SNMP). 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"; align=Center; \
77 title="Table 6.2: Example OID hierarchy"
79 {{EX:1.1}} Organization's OID
80 {{EX:1.1.1}} SNMP Elements
81 {{EX:1.1.2}} LDAP Elements
82 {{EX:1.1.2.1}} AttributeTypes
83 {{EX:1.1.2.1.1}} myAttribute
84 {{EX:1.1.2.2}} ObjectClasses
85 {{EX: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}} 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 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 of
214 {{slapd}}(8) supported syntax and matching rules.
216 The second attribute, {{EX:cn}}, is a subtype of {{EX:name}} hence
217 in inherits the syntax, matching rules, and usage of {{EX:name}}.
218 {{EX:commonName}} is an alternative name.
220 Neither attributes is restricted to a single value and both are
221 meant for usage by user applications. You likely won't need
222 specify other parameters such as {{EX:OBSOLETE}}.
224 The following subsections provide a couple of examples.
229 Many organizations maintain a single unique name for each user.
230 Though one could use {{EX:displayName}} ({{REF:RFC2798}}), but this
231 attribute is meant to be controlled by the user, not the
232 organization. We could just copy the definition of {{EX:displayName}}
233 from {{F:inetorgperson.schema}} and replace the OID, name, and
236 > attributetype ( 1.1.2.1.1 NAME 'myUniqueName'
237 > DESC 'unique name with my organization'
238 > EQUALITY caseIgnoreMatch
239 > SUBSTR caseIgnoreSubstringsMatch
240 > SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
243 However, if we desire this name to included in
244 {{EX:name}} assertions [e.g. {{EX:(name=*Jane*)}}], the attribute
245 could alternatively be defined as a subtype of {{EX:name}}, e.g.:
247 > attributetype ( 1.1.2.1.1 NAME 'myUniqueName'
248 > DESC 'unique name with my organization'
254 Many organizations maintain a photo of each each user. A
255 {{EX:myPhoto}} attribute type could be defined to hold a photo.
256 Of course, one could use just use {{EX:jpegPhoto}} ({{REF:RFC2798}})
257 (or a subtype) to hold the photo. However, you can only do
258 this if the photo is in {{JPEG File Interchange Format}}.
259 Alternatively, an attribute type which uses the {{Octet String}}
260 syntax can be defined, e.g.:
262 > attributetype ( 1.1.2.1.2 NAME 'myPhoto'
263 > DESC 'a photo (application defined format)'
264 > SYNTAX 1.3.6.1.4.1.1466.115.121.1.40
267 As noted in the description, LDAP has no knowledge of the
268 format of the photo. It's assumed that all applications
269 accessing this attribute agree on the handling of values.
271 If you want to support multiple photo format, one could define
272 a separate attributes type for each format, prefix the photo
273 with some typing information, or describe the value using
274 {{TERM:ASN.1}} and use the {{EX:;binary}} transfer option.
276 Another alternative is for the attribute only to hold a URI
277 pointing to the photo. You can model such an attribute after
278 {{EX:labeledURI}} ({{REF:RFC2079}}).
281 H3: Object Class Specification
283 The {{objectclasses}} directive is used to define a new object
284 class. The directive uses the same Object Class Description
285 (as defined in {{REF:RFC2252}}) used by the objectClasses
286 attribute found in the subschema subentry, e.g.:
288 E: objectclass <{{REF:RFC2252}} Object Class Description>
290 where Object Class Description is defined by the following
293 > ObjectClassDescription = "(" whsp
294 > numericoid whsp ; ObjectClass identifier
296 > [ "DESC" qdstring ]
297 > [ "OBSOLETE" whsp ]
298 > [ "SUP" oids ] ; Superior ObjectClasses
299 > [ ( "ABSTRACT" / "STRUCTURAL" / "AUXILIARY" ) whsp ]
300 > ; default structural
301 > [ "MUST" oids ] ; AttributeTypes
302 > [ "MAY" oids ] ; AttributeTypes
305 where whsp is a space ('{{EX: }}'), numericoid is a globally unique
306 OID in numeric form (e.g. {{EX:1.2.3}}), qdescrs is one or more
307 names, oids is one or more names and/or OIDs.
312 To define an auxiliary object class which allows
313 myPhoto to be added to any existing entry.
315 > objectclass ( 1.1.2.2.1 NAME 'myPhotoObject'
316 > DESC 'mixin myPhoto'
323 If your organization would like have a private structural
324 object class to instantiate users, you can subclass one of
325 the existing person classes, such as {{EX:inetOrgPerson}}
326 {{REF:RFC2798}}, and add any additional attributes which
329 > objectclass ( 1.1.2.2.2 NAME 'myPerson'
331 > MUST ( 'myUniqueName' $ 'givenName' )
335 The object class inherits the required/allowed attribute
336 types of {{EX:inetOrgPerson}} but requires {{EX:myUniqueName}}
337 and {EX:givenName}} and allows {{EX:myPhoto}}.