]> git.sur5r.net Git - openldap/blobdiff - doc/guide/admin/schema.sdf
Merge remote-tracking branch 'origin/mdb.master' into OPENLDAP_REL_ENG_2_4
[openldap] / doc / guide / admin / schema.sdf
index 20727eedec0f8f192ad8997f7569439a1e5c5723..7300b7e3471a093d4466927b9f58020f0ac2ab8a 100644 (file)
@@ -1,10 +1,13 @@
 # $OpenLDAP$
-# Copyright 1999-2000, The OpenLDAP Foundation, All Rights Reserved.
+# Copyright 1999-2013 The OpenLDAP Foundation, All Rights Reserved.
 # COPYING RESTRICTIONS APPLY, see COPYRIGHT.
 
 H1: Schema Specification
 
-This chapter describes how to extend the user schema used by {{slapd}}(8).
+This chapter describes how to extend the user schema used by
+{{slapd}}(8).  The chapter assumes the reader is familiar with the
+{{TERM:LDAP}}/{{TERM:X.500}} information model.
+
 The first section, {{SECT:Distributed Schema Files}} details optional
 schema definitions provided in the distribution and where to obtain
 other definitions.
@@ -16,16 +19,23 @@ export schema definitions from an LDAPv3 server and transform it
 to {{slapd.conf}}(5) format.
 !endif
 
+This chapter does not discuss how to extend system schema used by
+{{slapd}}(8) as this requires source code modification.  System
+schema includes all operational attribute types or any object class
+which allows or requires an operational attribute (directly or
+indirectly).
+
+
 H2: Distributed Schema Files
 
-OpenLDAP is distributed with a set of schema specifications for
+OpenLDAP Software is distributed with a set of schema specifications for
 your use.  Each set is defined in a file suitable for inclusion
 (using the {{EX:include}} directive) in your {{slapd.conf}}(5)
 file.  These schema files are normally installed in the
 {{F:/usr/local/etc/openldap/schema}} directory.
 
 !block table; colaligns="LR"; coltags="F,N"; align=Center; \
-       title="Table 6.1: Provided Schema Specifications"
+       title="Table 8.1: Provided Schema Specifications"
 File                   Description
 core.schema            OpenLDAP {{core}} (required)
 cosine.schema          Cosine and Internet X.500 (useful)
@@ -45,7 +55,7 @@ desired file in the global definitions portion of your
 >      include /usr/local/etc/openldap/schema/inetorgperson.schema
 
 Additional files may be available.  Please consult the OpenLDAP
-FAQ ({{URL:http://www.openldap.org/faq/}}).
+{{TERM:FAQ}} ({{URL:http://www.openldap.org/faq/}}).
 
 Note: You should not modify any of the schema items defined
 in provided files.
@@ -62,7 +72,7 @@ matching rules and system schema, but this requires some programming
 and hence is not discussed here.
 
 There are five steps to defining new schema:
-^      obtain Object Identifer
+^      obtain Object Identifier
 +      choose a name prefix
 +      create local schema file
 +      define custom attribute types (if necessary)
@@ -71,81 +81,66 @@ There are five steps to defining new schema:
 
 H3: Object Identifiers
 
-Each schema element is identified by a globally unique
-{{TERM[expand]OID}} (OID).  OIDs are also used to identify
-other objects.
-They are commonly found in protocols described by {{TERM:ASN.1}}.  In
+Each schema element is identified by a globally unique {{TERM[expand]OID}}
+(OID).  OIDs are also used to identify other objects.  They are
+commonly found in protocols described by {{TERM:ASN.1}}.  In
 particular, they are heavily used by the {{TERM[expand]SNMP}} (SNMP).
-As OIDs are hierarchical, your organization
-can obtain one OID and branch it as needed.  For example,
-if your organization were assigned OID {{EX:1.1}}, you could branch
-the tree as follows:
+As OIDs are hierarchical, your organization can obtain one OID and
+branch it as needed.  For example, if your organization were assigned
+OID {{EX:1.1}}, you could branch the tree as follows:
 
 !block table; colaligns="LR"; coltags="EX,N"; align=Center; \
-       title="Table 6.2: Example OID hierarchy"
+       title="Table 8.2: Example OID hierarchy"
 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.1.1      x-my-Attribute
 1.1.2.2                ObjectClasses
-1.1.2.2.1      myObjectClass
+1.1.2.2.1      x-my-ObjectClass
 !endblock
 
 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
-something more sophisticated such as the {{OpenLDAP OID Registry}}
-({{URL:http://www.openldap.org/faq/index.cgi?file=197}}).
-
-For more information about Object Identifers (and a listing
-service) see {{URL:http://www.alvestrand.no/harald/objectid/}}.
-
-.{{Under no circumstances should you hijack OID namespace!}} 
-
-To obtain a fully registered OID at {{no cost}}, apply for an OID
-under the {{ORG[expand]IANA}} (IANA) maintained {{Private Enterprise}}
-arch.  Any private enterprise (organization) may request an OID to
-be assigned under this arch.  Just fill out the {{ORG:IANA}} form
-at {{URL: 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 {{EX:1.3.6.1.4.1.X}} where {{EX: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.
+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 something more sophisticated such as the {{OpenLDAP OID Registry}} ({{URL:http://www.openldap.org/faq/index.cgi?file=197}}).
 
-Alternatively, OID name space may be available from a national
-authority (e.g., ANSI).
+For more information about Object Identifiers (and a listing service)
+see {{URL:http://www.alvestrand.no/objectid/}}.
 
-For private experiments, OIDs under {{EX:1.1}} may be used.  The OID
-{{EX:1.1}} arc is dead name space.
+.{{Under no circumstances should you hijack OID namespace!}}
 
+To obtain a registered OID at {{no cost}}, apply for a OID
+under the {{ORG[expand]IANA}} (ORG:IANA) maintained {{Private Enterprise}} arc.  
+Any private enterprise (organization) may request a {{TERM[expand]PEN}} (PEN) to be assigned under this arc. Just fill out the IANA form at {{URL: http://pen.iana.org/pen/PenApplication.page}} and your official PEN will be sent to you usually within a few days. Your base OID will be something like {{EX:1.3.6.1.4.1.X}} where {{EX:X}} is an integer.
+
+Note: PENs obtained using this form may be used for any purpose
+including identifying LDAP schema elements.
+
+Alternatively, OID name space may be available from a national
+authority (e.g., {{ORG:ANSI}}, {{ORG:BSI}}).
 
-H3: Name Prefix
+
+H3: Naming Elements
 
 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 chosen a short prefix '{{EX: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 '{{EX:deFirm}}' (German company) or
-'{{EX:comExample}}' (elements associated with organization associated
-with {{EX:example.com}}).
+element, you should provide at least one textual name for each
+element.  Names should be registered with the {{ORG:IANA}} or
+prefixed with "x-" to place in the "private use" name space.
+
+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 (this
+is assured if you registered names or use names beginning with "x-").
+
+It is noted that you can obtain your own registered name
+prefix so as to avoid having to register your names individually.
+See {{REF:RFC4520}} for details.
+
+In the examples below, we have used a short prefix '{{EX:x-my-}}'.
+Such a short prefix would only be suitable for a very large, global
+organization.  In general, we recommend something like '{{EX:x-de-Firm-}}'
+(German company) or '{{EX:x-com-Example}}' (elements associated with
+organization associated with {{EX:example.com}}).
 
 
 H3: Local schema file
@@ -170,13 +165,13 @@ H3: 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 {{REF:RFC2252}}) used by the attributeTypes
+(as defined in {{REF:RFC4512}}) used by the attributeTypes
 attribute found in the subschema subentry, e.g.:
 
-E:     attributetype <{{REF:RFC2252}} Attribute Type Description>
+E:     attributetype <{{REF:RFC4512}} Attribute Type Description>
 
 where Attribute Type Description is defined by the following
-{{TERM:BNF}}:
+{{TERM:ABNF}}:
 
 >      AttributeTypeDescription = "(" whsp
 >            numericoid whsp              ; AttributeType identifier
@@ -215,7 +210,7 @@ in {{F:core.schema}} as:
 >              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' )
+>      attributeType ( 2.5.4.3 NAME ( 'cn' 'commonName' )
 >              DESC 'common name(s) assciated with the object'
 >              SUP name )
 
@@ -224,56 +219,50 @@ and a brief description.  Each name is an alias for the OID.
 {{slapd}}(8) returns the first listed name when returning results.
 
 The first attribute, {{EX:name}}, holds values of {{EX:directoryString}}
-(UTF-8 encoded Unicode) syntax.  The syntax is specified by OID
-(1.3.6.1.4.1.1466.115.121.1.15 identifies the directoryString
-syntax).  A length recommendation of 32768 is specified.  Servers
-should support values of this length, but may support longer values
-The field does NOT specify a size constraint, so is ignored on
-servers (such as slapd) which don't impose such size limits.  In
-addition, the equality and substring matching uses case ignore
-rules.  Below are tables listing commonly used syntax and
-matching rules (OpenLDAP supports these and many more).
+({{TERM:UTF-8}} encoded Unicode) syntax.  The syntax is
+specified by OID (1.3.6.1.4.1.1466.115.121.1.15 identifies the
+directoryString syntax).  A length recommendation of 32768 is
+specified.  Servers should support values of this length, but may
+support longer values. The field does NOT specify a size constraint,
+so is ignored on servers (such as slapd) which don't impose such
+size limits.  In addition, the equality and substring matching uses
+case ignore rules.  Below are tables listing commonly used syntax
+and matching rules ({{slapd}}(8) supports these and many more).
 
 !block table; align=Center; coltags="EX,EX,N"; \
-       title="Table 6.3: Commonly Used Syntaxes"
+       title="Table 8.3: Commonly Used Syntaxes"
 Name                   OID                             Description
 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
+directoryString                1.3.6.1.4.1.1466.115.121.1.15   Unicode (UTF-8) string
+distinguishedName      1.3.6.1.4.1.1466.115.121.1.12   LDAP {{TERM:DN}}
+integer                        1.3.6.1.4.1.1466.115.121.1.27   integer
+numericString          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
+octetString            1.3.6.1.4.1.1466.115.121.1.40   arbitrary octets
 !endblock
 
 > 
 
 !block table; align=Center; coltags="EX,N"; \
-       title="Table 6.4: Commonly Used Matching Rules"
-Name                           Type            Description
-booleanMatch                   equality        boolean
-octetStringMatch               equality        octet string
-objectIdentiferMatch           equality        OID
-distinguishedNameMatch         equality        DN
-uniqueMemberMatch              equality        Name 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
+       title="Table 8.4: Commonly Used Matching Rules"
+Name                                   Type            Description
+booleanMatch                           equality        boolean
+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
+distinguishedNameMatch                 equality        distinguished name
+integerMatch                           equality        integer
+integerOrderingMatch                   ordering        integer
+numericStringMatch                     equality        numerical
+numericStringOrderingMatch             ordering        numerical
+numericStringSubstringsMatch           substrings      numerical
+octetStringMatch                       equality        octet string
+octetStringOrderingMatch               ordering        octet string
+octetStringSubstringsMatch     ordering        octet string
+objectIdentiferMatch                   equality        object identifier
 !endblock
 
 The second attribute, {{EX:cn}}, is a subtype of {{EX:name}} hence
@@ -286,7 +275,7 @@ for usage by user applications.  Neither is obsolete nor collective.
 The following subsections provide a couple of examples.
 
 
-H4: myUniqueName
+H4: x-my-UniqueName
 
 Many organizations maintain a single unique name for each user.
 Though one could use {{EX:displayName}} ({{REF:RFC2798}}), this
@@ -295,33 +284,33 @@ organization.  We could just copy the definition of {{EX:displayName}}
 from {{F:inetorgperson.schema}} and replace the OID, name, and
 description, e.g:
 
->      attributetype ( 1.1.2.1.1 NAME 'myUniqueName'
+>      attributetype ( 1.1.2.1.1 NAME 'x-my-UniqueName'
 >              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
-{{EX:name}} assertions [e.g. {{EX:(name=*Jane*)}}], the attribute
-could alternatively be defined as a subtype of {{EX:name}}, e.g.:
+However, if we want this name to be used in {{EX:name}} assertions,
+e.g. {{EX:(name=*Jane*)}}, the attribute could alternatively be
+defined as a subtype of {{EX:name}}, e.g.:
 
->      attributetype ( 1.1.2.1.1 NAME 'myUniqueName'
+>      attributetype ( 1.1.2.1.1 NAME 'x-my-UniqueName'
 >              DESC 'unique name with my organization' 
 >              SUP name )
 
 
-H4: myPhoto
+H4: x-my-Photo
 
 Many organizations maintain a photo of each each user.  A
-{{EX:myPhoto}} attribute type could be defined to hold a photo.
+{{EX:x-my-Photo}} attribute type could be defined to hold a photo.
 Of course, one could use just use {{EX:jpegPhoto}} ({{REF: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'
+>      attributetype ( 1.1.2.1.2 NAME 'x-my-Photo'
 >              DESC 'a photo (application defined format)' 
 >              SYNTAX 1.3.6.1.4.1.1466.115.121.1.40
 >              SINGLE-VALUE )
@@ -340,7 +329,7 @@ pointing to the photo.  You can model such an attribute after
 {{EX:labeledURI}} ({{REF:RFC2079}}) or simply create a subtype,
 e.g.:
 
->      attributetype ( 1.1.2.1.3 NAME 'myPhotoURI'
+>      attributetype ( 1.1.2.1.3 NAME 'x-my-PhotoURI'
 >              DESC 'URI and optional label referring to a photo' 
 >              SUP labeledURI )
 
@@ -349,13 +338,13 @@ H3: 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 {{REF:RFC2252}}) used by the objectClasses
+(as defined in {{REF:RFC4512}}) used by the objectClasses
 attribute found in the subschema subentry, e.g.:
 
-E:     objectclass <{{REF:RFC2252}} Object Class Description>
+E:     objectclass <{{REF:RFC4512}} Object Class Description>
 
 where Object Class Description is defined by the following
-{{TERM:BNF}}:
+{{TERM:ABNF}}:
 
 >      ObjectClassDescription = "(" whsp
 >              numericoid whsp      ; ObjectClass identifier
@@ -370,22 +359,22 @@ where Object Class Description is defined by the following
 >              whsp ")"
 
 where whsp is a space ('{{EX: }}'), numericoid is a globally unique
-OID in numeric form (e.g. {{EX:1.1.0}}), qdescrs is one or more
+OID in dotted-decimal form (e.g. {{EX:1.1.0}}), qdescrs is one or more
 names, and oids is one or more names and/or OIDs.
 
 
-H4: myPhotoObject
+H4: x-my-PhotoObject
 
 To define an {{auxiliary}} object class which allows
-myPhoto to be added to any existing entry.
+x-my-Photo to be added to any existing entry.
 
->      objectclass ( 1.1.2.2.1 NAME 'myPhotoObject'
->              DESC 'mixin myPhoto'
+>      objectclass ( 1.1.2.2.1 NAME 'x-my-PhotoObject'
+>              DESC 'mixin x-my-Photo'
 >              AUXILIARY
->              MAY myPhoto )
+>              MAY x-my-Photo )
 
 
-H4: myPerson
+H4: x-my-Person
 
 If your organization would like have a private {{structural}}
 object class to instantiate users, you can subclass one of
@@ -393,79 +382,83 @@ the existing person classes, such as {{EX:inetOrgPerson}}
 ({{REF:RFC2798}}), and add any additional attributes which
 you desire.
 
->      objectclass ( 1.1.2.2.2 NAME 'myPerson'
+>      objectclass ( 1.1.2.2.2 NAME 'x-my-Person'
 >              DESC 'my person'
 >              SUP inetOrgPerson
->              MUST ( myUniqueName $ givenName )
->              MAY myPhoto )
+>              MUST ( x-my-UniqueName $ givenName )
+>              MAY x-my-Photo )
 
 The object class inherits the required/allowed attribute
-types of {{EX:inetOrgPerson}} but requires {{EX:myUniqueName}}
-and {{EX:givenName}} and allows {{EX:myPhoto}}.
+types of {{EX:inetOrgPerson}} but requires {{EX:x-my-UniqueName}}
+and {{EX:givenName}} and allows {{EX:x-my-Photo}}.
 
 !if 0
 H2: Transferring Schema
 
-Since the {{slapd.conf}}(5) schema directives use {{REF:RFC2252}}
-format values, you can extract schema elements published by
-any LDAPv3 server and easily construct directives for use with
+Since the {{slapd.conf}}(5) schema directives use {{REF:RFC4512}}
+format values, you can extract schema elements published by any
+{{TERM:LDAPv3}} server and easily construct directives for use with
 {{slapd}}(8).
 
 LDAPv3 servers publish schema elements in special {{subschema}}
-entries (or subentries).  {{slapd}}(8) publishes a single subschema
-entry normally named {{EX:cn=Subschema}}.  In a server which
-supports a single subschema subentry, the DN of the subschema
-subenty can usually be found by examining the value of the
-{{EX:subschemaSubentry}} attribute type in the {{root DSE}}.
-Other servers may publish multiple subschema entries.  These
-can be located by examining the {{EX:subschemaSubentry}} attribute
-contained in the entry at the root of each administrative context.
+entries (or subentries).  While {{slapd}}(8) publishes a single
+subschema subentry normally named {{EX:cn=Subschema}}, this behavior
+cannot be expected from other servers.  The subschema subentry
+controlling a particular entry can be obtained by examining the
+{{EX:subschemaSubentry}} attribute contained in the entry at the
+root of each administrative context.  For example,
+
+>      ldapsearch -LLL -x -b "dc=example,dc=com" -s base "(objectclass=*)" subschemaSubentry
 
 To obtain the schema from a subschema subentry, you can use
 ldapsearch(1) as follows (replace the search base as needed):
 
 >      ldapsearch -LLL -x -b "cn=Subschema" -s base "(objectclass=subschema)" attributeTypes objectClasses
 
+where "cn=Subschema" is the value of subschemaSubentry returned in
+the prior search.
+
 This will return {{TERM:LDIF}} output containing many type/value
 pairs.  The following is an abbreviated example:
 
 >      dn: cn=Subschema
->      attributeTypes: ( 1.1.2.1.1 NAME 'myUniqueName' DESC 'unique name wi
->       th my organization' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubst
->       ringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE )
->      attributeTypes: ( 1.1.2.1.2 NAME 'myPhoto' DESC 'a photo (applicatio
+>      objectClasses: ( 1.1.2.2.2 NAME 'x-my-Person' DESC 'my person' SUP inet
+>       OrgPerson MUST ( x-my-UniqueName $ givenName ) MAY x-my-Photo )
+>      attributeTypes: ( 1.1.2.1.1 NAME 'x-my-UniqueName' DESC 'unique name wi
+>       th my organization' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstrin
+>       gsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE )
+>      attributeTypes: ( 1.1.2.1.2 NAME 'x-my-Photo' DESC 'a photo (applicatio
 >       n defined format)' SYNTAX 1.3.6.1.4.1.1466.115.121.1.40
->      objectClasses: ( 1.1.2.2.2 NAME 'myPerson' DESC 'my person' SUP inet
->       OrgPerson MUST ( myUniqueName $ givenName ) MAY myPhoto )
 
 Capture the output of the search in a file and then edit the file:
 
 + to contain only desired type/value pairs
 ^ join LDIF continuation lines
 ^ replace attribute type with directive name
-(e.g. {{EX:s/attributeTypes:/attributeType/}} and
-{{EX:s/objectClasses:/objectClass/}}).
+(e.g. {{EX:s/attributeTypes:/attributeType /}} and
+{{EX:s/objectClasses:/objectClass /}}).
+^ reorder lines so each element is defined before first use
 ^ continue long directives over multiple lines
 
 For the three type/value pairs in our example, the edit should
 result in a file with contains of:
 
->      attributetype ( 1.1.2.1.1 NAME 'myUniqueName'
+>      attributetype ( 1.1.2.1.1 NAME 'x-my-UniqueName'
 >              DESC 'unique name with my organization' 
 >              EQUALITY caseIgnoreMatch
 >              SUBSTR caseIgnoreSubstringsMatch
 >              SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
 >              SINGLE-VALUE )
->      attributeType ( 1.1.2.1.2 NAME 'myPhoto'
+>      attributeType ( 1.1.2.1.2 NAME 'x-my-Photo'
 >              DESC 'a photo (application defined format)'
 >              SYNTAX 1.3.6.1.4.1.1466.115.121.1.40
->      objectClass ( 1.1.2.2.2 NAME 'myPerson'
+>      objectClass ( 1.1.2.2.2 NAME 'x-my-Person'
 >              DESC 'my person'
 >              SUP inetOrgPerson
->              MUST ( myUniqueName $ givenName )
->              MAY myPhoto )
+>              MUST ( x-my-UniqueName $ givenName )
+>              MAY x-my-Photo )
 
-Save in an appropriately named file (e.g. {{F:my.schema}}).
+Save in an appropriately named file (e.g. {{F:local.schema}}).
 You may now include this file in your {{slapd.conf}}(5) file.
 !endif
 
@@ -473,10 +466,10 @@ You may now include this file in your {{slapd.conf}}(5) file.
 H3: OID Macros
 
 To ease the management and use of OIDs, {{slapd}}(8) supports
-{{Object Identifier}} macros.  The {{EX:objectIdentifier}} is used
-to equate a macro (name) with a OID.  The OID may possibly be derived
-from a previously defined OID macro.   The {{slapd.conf}}(5) syntax
-is:
+{{Object Identifier}} macros.  The {{EX:objectIdentifier}} directive
+is used to equate a macro (name) with a OID.  The OID may possibly
+be derived from a previously defined OID macro.   The {{slapd.conf}}(5)
+syntax is:
 
 E:     objectIdentifier <name> { <oid> | <name>[:<suffix>] }
 
@@ -488,11 +481,11 @@ and their use in defining schema elements:
 >      objectIdentifier myLDAP myOID:2
 >      objectIdentifier myAttributeType        myLDAP:1
 >      objectIdentifier myObjectClass  myLDAP:2
->      attributetype ( myAttributeType:3 NAME 'myPhotoURI'
+>      attributetype ( myAttributeType:3 NAME 'x-my-PhotoURI'
 >              DESC 'URI and optional label referring to a photo' 
 >              SUP labeledURI )
->      objectclass ( myObjectClass:1 NAME 'myPhotoObject'
->              DESC 'mixin myPhoto'
+>      objectclass ( myObjectClass:1 NAME 'x-my-PhotoObject'
+>              DESC 'mixin x-my-Photo'
 >              AUXILIARY
->              MAY myPhoto )
+>              MAY x-my-Photo )