Skip to main content

4. Directory Schema

As defined in [X.501]:

  The Directory Schema is a set of definitions and constraints
  concerning the structure of the DIT, the possible ways entries are
  named, the information that can be held in an entry, the
  attributes used to represent that information and their
  organization into hierarchies to facilitate search and retrieval
  of the information and the ways in which values of attributes may
  be matched in attribute value and matching rule assertions.

  NOTE 1 - The schema enables the Directory system to, for example:

  - prevent the creation of subordinate entries of the wrong
    object-class (e.g., a country as a subordinate of a person);

  - prevent the addition of attribute-types to an entry
    inappropriate to the object-class (e.g., a serial number to a
    person's entry);

  - prevent the addition of an attribute value of a syntax not
    matching that defined for the attribute-type (e.g., a printable
    string to a bit string).

  Formally, the Directory Schema comprises a set of:

  a) Name Form definitions that define primitive naming relations
     for structural object classes;

  b) DIT Structure Rule definitions that define the names that
     entries may have and the ways in which the entries may be
     related to one another in the DIT;

  c) DIT Content Rule definitions that extend the specification of
     allowable attributes for entries beyond those indicated by the
     structural object classes of the entries;

  d) Object Class definitions that define the basic set of mandatory
     and optional attributes that shall be present, and may be
     present, respectively, in an entry of a given class, and which
     indicate the kind of object class that is being defined;

  e) Attribute Type definitions that identify the object identifier
     by which an attribute is known, its syntax, associated matching
     rules, whether it is an operational attribute and if so its
     type, whether it is a collective attribute, whether it is
     permitted to have multiple values and whether or not it is
     derived from another attribute type;

  f) Matching Rule definitions that define matching rules.

  And in LDAP:

  g) LDAP Syntax definitions that define encodings used in LDAP.

4.1. Schema Definitions​

Schema definitions in this section are described using ABNF and rely on the common productions specified in Section 1.2 as well as these:

  noidlen = numericoid [ LCURLY len RCURLY ]
  len = number

  oids = oid / ( LPAREN WSP oidlist WSP RPAREN )
  oidlist = oid *( WSP DOLLAR WSP oid )

  extensions = *( SP xstring SP qdstrings )
  xstring = "X" HYPHEN 1*( ALPHA / HYPHEN / USCORE )

  qdescrs = qdescr / ( LPAREN WSP qdescrlist WSP RPAREN )
  qdescrlist = [ qdescr *( SP qdescr ) ]
  qdescr = SQUOTE descr SQUOTE

  qdstrings = qdstring / ( LPAREN WSP qdstringlist WSP RPAREN )
  qdstringlist = [ qdstring *( SP qdstring ) ]
  qdstring = SQUOTE dstring SQUOTE
  dstring = 1*( QS / QQ / QUTF8 )   ; escaped UTF-8 string

  QQ =  ESC %x32 %x37 ; "\27"
  QS =  ESC %x35 ( %x43 / %x63 ) ; "\5C" / "\5c"

  ; Any UTF-8 encoded Unicode character
  ; except %x27 ("\'") and %x5C ("\")
  QUTF8    = QUTF1 / UTFMB

  ; Any ASCII character except %x27 ("\'") and %x5C ("\")
  QUTF1    = %x00-26 / %x28-5B / %x5D-7F

Schema definitions in this section also share a number of common terms.

The NAME field provides a set of short names (descriptors) that are to be used as aliases for the OID.

The DESC field optionally allows a descriptive string to be provided by the directory administrator and/or implementor. While specifications may suggest a descriptive string, there is no requirement that the suggested (or any) descriptive string be used.

The OBSOLETE field, if present, indicates the element is not active.

Implementors should note that future versions of this document may expand these definitions to include additional terms. Terms whose identifier begins with "X-" are reserved for private experiments and are followed by and tokens.

4.1.1. Object Class Definitions​

Object Class definitions are written according to the ABNF:

 ObjectClassDescription = LPAREN WSP
     numericoid                 ; object identifier
     [ SP "NAME" SP qdescrs ]   ; short names (descriptors)
     [ SP "DESC" SP qdstring ]  ; description
     [ SP "OBSOLETE" ]          ; not active
     [ SP "SUP" SP oids ]       ; superior object classes
     [ SP kind ]                ; kind of class
     [ SP "MUST" SP oids ]      ; attribute types
     [ SP "MAY" SP oids ]       ; attribute types
     extensions WSP RPAREN

 kind = "ABSTRACT" / "STRUCTURAL" / "AUXILIARY"

where: is object identifier assigned to this object class; NAME are short names (descriptors) identifying this object class; DESC is a short descriptive string; OBSOLETE indicates this object class is not active; SUP specifies the direct superclasses of this object class; the kind of object class is indicated by one of ABSTRACT, STRUCTURAL, or AUXILIARY (the default is STRUCTURAL); MUST and MAY specify the sets of required and allowed attribute types, respectively; and describe extensions.

4.1.2. Attribute Types​

Attribute Type definitions are written according to the ABNF:

 AttributeTypeDescription = LPAREN WSP
     numericoid                    ; object identifier
     [ SP "NAME" SP qdescrs ]      ; short names (descriptors)
     [ SP "DESC" SP qdstring ]     ; description
     [ SP "OBSOLETE" ]             ; not active
     [ SP "SUP" SP oid ]           ; supertype
     [ SP "EQUALITY" SP oid ]      ; equality matching rule
     [ SP "ORDERING" SP oid ]      ; ordering matching rule
     [ SP "SUBSTR" SP oid ]        ; substrings matching rule
     [ SP "SYNTAX" SP noidlen ]    ; value syntax
     [ SP "SINGLE-VALUE" ]         ; single-value
     [ SP "COLLECTIVE" ]           ; collective
     [ SP "NO-USER-MODIFICATION" ] ; not user modifiable
     [ SP "USAGE" SP usage ]       ; usage
     extensions WSP RPAREN         ; extensions

 usage = "userApplications"     /  ; user
         "directoryOperation"   /  ; directory operational
         "distributedOperation" /  ; DSA-shared operational
         "dSAOperation"            ; DSA-specific operational

where: is object identifier assigned to this attribute type; NAME are short names (descriptors) identifying this attribute type; DESC is a short descriptive string; OBSOLETE indicates this attribute type is not active; SUP oid specifies the direct supertype of this type; EQUALITY, ORDERING, and SUBSTR provide the oid of the equality, ordering, and substrings matching rules, respectively; SYNTAX identifies value syntax by object identifier and may suggest a minimum upper bound; SINGLE-VALUE indicates attributes of this type are restricted to a single value; COLLECTIVE indicates this attribute type is collective [X.501][RFC3671]; NO-USER-MODIFICATION indicates this attribute type is not user modifiable; USAGE indicates the application of this attribute type; and describe extensions.

Each attribute type description must contain at least one of the SUP or SYNTAX fields. If no SYNTAX field is provided, the attribute type description takes its value from the supertype.

If SUP field is provided, the EQUALITY, ORDERING, and SUBSTRING fields, if not specified, take their value from the supertype.

Usage of userApplications, the default, indicates that attributes of this type represent user information. That is, they are user attributes.

A usage of directoryOperation, distributedOperation, or dSAOperation indicates that attributes of this type represent operational and/or administrative information. That is, they are operational attributes.

directoryOperation usage indicates that the attribute of this type is a directory operational attribute. distributedOperation usage indicates that the attribute of this type is a DSA-shared usage operational attribute. dSAOperation usage indicates that the attribute of this type is a DSA-specific operational attribute.

COLLECTIVE requires usage userApplications. Use of collective attribute types in LDAP is discussed in [RFC3671].

NO-USER-MODIFICATION requires an operational usage.

Note that the does not list the matching rules that can be used with that attribute type in an extensibleMatch search filter [RFC4511]. This is done using the 'matchingRuleUse' attribute described in Section 4.1.4.

This document refines the schema description of X.501 by requiring that the SYNTAX field in an be a string representation of an object identifier for the LDAP string syntax definition, with an optional indication of the suggested minimum bound of a value of this attribute.

A suggested minimum upper bound on the number of characters in a value with a string-based syntax, or the number of bytes in a value for all other syntaxes, may be indicated by appending this bound count inside of curly braces following the syntax's OBJECT IDENTIFIER in an Attribute Type Description. This bound is not part of the syntax name itself. For instance, "1.3.6.4.1.1466.0{64}" suggests that server implementations should allow a string to be 64 characters long, although they may allow longer strings. Note that a single character of the Directory String syntax may be encoded in more than one octet since UTF-8 [RFC3629] is a variable-length encoding.

4.1.3. Matching Rules​

Matching rules are used in performance of attribute value assertions, such as in performance of a Compare operation. They are also used in evaluating search filters, determining which individual values are to be added or deleted during performance of a Modify operation, and in comparing distinguished names.

Each matching rule is identified by an object identifier (OID) and, optionally, one or more short names (descriptors).

Matching rule definitions are written according to the ABNF:

 MatchingRuleDescription = LPAREN WSP
     numericoid                 ; object identifier
     [ SP "NAME" SP qdescrs ]   ; short names (descriptors)
     [ SP "DESC" SP qdstring ]  ; description
     [ SP "OBSOLETE" ]          ; not active
     SP "SYNTAX" SP numericoid  ; assertion syntax
     extensions WSP RPAREN      ; extensions

where: is object identifier assigned to this matching rule; NAME are short names (descriptors) identifying this matching rule; DESC is a short descriptive string; OBSOLETE indicates this matching rule is not active; SYNTAX identifies the assertion syntax (the syntax of the assertion value) by object identifier; and describe extensions.

4.1.4. Matching Rule Uses​

A matching rule use lists the attribute types that are suitable for use with an extensibleMatch search filter.

Matching rule use descriptions are written according to the following ABNF:

 MatchingRuleUseDescription = LPAREN WSP
     numericoid                 ; object identifier
     [ SP "NAME" SP qdescrs ]   ; short names (descriptors)
     [ SP "DESC" SP qdstring ]  ; description
     [ SP "OBSOLETE" ]          ; not active
     SP "APPLIES" SP oids       ; attribute types
     extensions WSP RPAREN      ; extensions

where: is the object identifier of the matching rule associated with this matching rule use description; NAME are short names (descriptors) identifying this matching rule use; DESC is a short descriptive string; OBSOLETE indicates this matching rule use is not active; APPLIES provides a list of attribute types the matching rule applies to; and describe extensions.

4.1.5. LDAP Syntaxes​

LDAP Syntaxes of (attribute and assertion) values are described in terms of ASN.1 [X.680] and, optionally, have an octet string encoding known as the LDAP-specific encoding. Commonly, the LDAP-specific encoding is constrained to a string of Unicode [Unicode] characters in UTF-8 [RFC3629] form.

Each LDAP syntax is identified by an object identifier (OID).

LDAP syntax definitions are written according to the ABNF:

 SyntaxDescription = LPAREN WSP
     numericoid                 ; object identifier
     [ SP "DESC" SP qdstring ]  ; description
     extensions WSP RPAREN      ; extensions

where: is the object identifier assigned to this LDAP syntax; DESC is a short descriptive string; and describe extensions.

4.1.6. DIT Content Rules​

A DIT content rule is a "rule governing the content of entries of a particular structural object class" [X.501].

For DIT entries of a particular structural object class, a DIT content rule specifies which auxiliary object classes the entries are allowed to belong to and which additional attributes (by type) are required, allowed, or not allowed to appear in the entries.

The list of precluded attributes cannot include any attribute listed as mandatory in the rule, the structural object class, or any of the allowed auxiliary object classes.

Each content rule is identified by the object identifier, as well as any short names (descriptors), of the structural object class it applies to.

An entry may only belong to auxiliary object classes listed in the governing content rule.

An entry must contain all attributes required by the object classes the entry belongs to as well as all attributes required by the governing content rule.

An entry may contain any non-precluded attributes allowed by the object classes the entry belongs to as well as all attributes allowed by the governing content rule.

An entry cannot include any attribute precluded by the governing content rule.

An entry is governed by (if present and active in the subschema) the DIT content rule that applies to the structural object class of the entry (see Section 2.4.2). If no active rule is present for the entry's structural object class, the entry's content is governed by the structural object class (and possibly other aspects of user and system schema). DIT content rules for superclasses of the structural object class of an entry are not applicable to that entry.

DIT content rule descriptions are written according to the ABNF:

 DITContentRuleDescription = LPAREN WSP
     numericoid                 ; object identifier
     [ SP "NAME" SP qdescrs ]   ; short names (descriptors)
     [ SP "DESC" SP qdstring ]  ; description
     [ SP "OBSOLETE" ]          ; not active
     [ SP "AUX" SP oids ]       ; auxiliary object classes
     [ SP "MUST" SP oids ]      ; attribute types
     [ SP "MAY" SP oids ]       ; attribute types
     [ SP "NOT" SP oids ]       ; attribute types
     extensions WSP RPAREN      ; extensions

where: is the object identifier of the structural object class associated with this DIT content rule; NAME are short names (descriptors) identifying this DIT content rule; DESC is a short descriptive string; OBSOLETE indicates this DIT content rule use is not active; AUX specifies a list of auxiliary object classes that entries subject to this DIT content rule may belong to;

 MUST, MAY, and NOT specify lists of attribute types that are
     required, allowed, or precluded, respectively, from appearing
     in entries subject to this DIT content rule; and
 <extensions> describe extensions.

4.1.7. DIT Structure Rules and Name Forms​

It is sometimes desirable to regulate where object and alias entries can be placed in the DIT and how they can be named based upon their structural object class.

4.1.7.1. DIT Structure Rules​

A DIT structure rule is a "rule governing the structure of the DIT by specifying a permitted superior to subordinate entry relationship. A structure rule relates a name form, and therefore a structural object class, to superior structure rules. This permits entries of the structural object class identified by the name form to exist in the DIT as subordinates to entries governed by the indicated superior structure rules" [X.501].

DIT structure rule descriptions are written according to the ABNF:

 DITStructureRuleDescription = LPAREN WSP
     ruleid                     ; rule identifier
     [ SP "NAME" SP qdescrs ]   ; short names (descriptors)
     [ SP "DESC" SP qdstring ]  ; description
     [ SP "OBSOLETE" ]          ; not active
     SP "FORM" SP oid           ; NameForm
     [ SP "SUP" ruleids ]       ; superior rules
     extensions WSP RPAREN      ; extensions

 ruleids = ruleid / ( LPAREN WSP ruleidlist WSP RPAREN )
 ruleidlist = ruleid *( SP ruleid )
 ruleid = number

where: is the rule identifier of this DIT structure rule; NAME are short names (descriptors) identifying this DIT structure rule; DESC is a short descriptive string; OBSOLETE indicates this DIT structure rule use is not active; FORM is specifies the name form associated with this DIT structure rule; SUP identifies superior rules (by rule id); and describe extensions.

If no superior rules are identified, the DIT structure rule applies to an autonomous administrative point (e.g., the root vertex of the subtree controlled by the subschema) [X.501].

4.1.7.2. Name Forms​

A name form "specifies a permissible RDN for entries of a particular structural object class. A name form identifies a named object class and one or more attribute types to be used for naming (i.e., for the RDN). Name forms are primitive pieces of specification used in the definition of DIT structure rules" [X.501].

Each name form indicates the structural object class to be named, a set of required attribute types, and a set of allowed attribute types. A particular attribute type cannot be in both sets.

Entries governed by the form must be named using a value from each required attribute type and zero or more values from the allowed attribute types.

Each name form is identified by an object identifier (OID) and, optionally, one or more short names (descriptors).

Name form descriptions are written according to the ABNF:

 NameFormDescription = LPAREN WSP
     numericoid                 ; object identifier
     [ SP "NAME" SP qdescrs ]   ; short names (descriptors)
     [ SP "DESC" SP qdstring ]  ; description
     [ SP "OBSOLETE" ]          ; not active
     SP "OC" SP oid             ; structural object class
     SP "MUST" SP oids          ; attribute types
     [ SP "MAY" SP oids ]       ; attribute types
     extensions WSP RPAREN      ; extensions

where: is object identifier that identifies this name form; NAME are short names (descriptors) identifying this name form; DESC is a short descriptive string; OBSOLETE indicates this name form is not active; OC identifies the structural object class this rule applies to, MUST and MAY specify the sets of required and allowed, respectively, naming attributes for this name form; and describe extensions.

All attribute types in the required ("MUST") and allowed ("MAY") lists shall be different.

4.2. Subschema Subentries​

Subschema (sub)entries are used for administering information about the directory schema. A single subschema (sub)entry contains all schema definitions (see Section 4.1) used by entries in a particular part of the directory tree.

Servers that follow X.500(93) models SHOULD implement subschema using the X.500 subschema mechanisms (as detailed in Section 12 of [X.501]), so these are not ordinary object entries but subentries (see Section 3.2). LDAP clients SHOULD NOT assume that servers implement any of the other aspects of X.500 subschema.

Servers MAY allow subschema modification. Procedures for subschema modification are discussed in Section 14.5 of [X.501].

A server that masters entries and permits clients to modify these entries SHALL implement and provide access to these subschema (sub)entries including providing a 'subschemaSubentry' attribute in each modifiable entry. This is so clients may discover the attributes and object classes that are permitted to be present. It is strongly RECOMMENDED that all other servers implement this as well.

The value of the 'subschemaSubentry' attribute is the name of the subschema (sub)entry holding the subschema controlling the entry.

  ( 2.5.18.10 NAME 'subschemaSubentry'
    EQUALITY distinguishedNameMatch
    SYNTAX 1.3.6.1.4.1.1466.115.121.1.12
    SINGLE-VALUE NO-USER-MODIFICATION
    USAGE directoryOperation )

The 'distinguishedNameMatch' matching rule and the DistinguishedName (1.3.6.1.4.1.1466.115.121.1.12) syntax are defined in [RFC4517].

Subschema is held in (sub)entries belonging to the subschema auxiliary object class.

  ( 2.5.20.1 NAME 'subschema' AUXILIARY
    MAY ( dITStructureRules $ nameForms $ ditContentRules $
      objectClasses $ attributeTypes $ matchingRules $
      matchingRuleUse ) )

The 'ldapSyntaxes' operational attribute may also be present in subschema entries.

Servers MAY provide additional attributes (described in other documents) in subschema (sub)entries.

Servers SHOULD provide the attributes 'createTimestamp' and 'modifyTimestamp' in subschema (sub)entries, in order to allow clients to maintain their caches of schema information.

The following subsections provide attribute type definitions for each of schema definition attribute types.

4.2.1. 'objectClasses'​

This attribute holds definitions of object classes.

  ( 2.5.21.6 NAME 'objectClasses'
    EQUALITY objectIdentifierFirstComponentMatch
    SYNTAX 1.3.6.1.4.1.1466.115.121.1.37
    USAGE directoryOperation )

The 'objectIdentifierFirstComponentMatch' matching rule and the ObjectClassDescription (1.3.6.1.4.1.1466.115.121.1.37) syntax are defined in [RFC4517].

4.2.2. 'attributeTypes'​

This attribute holds definitions of attribute types.

  ( 2.5.21.5 NAME 'attributeTypes'
    EQUALITY objectIdentifierFirstComponentMatch
    SYNTAX 1.3.6.1.4.1.1466.115.121.1.3
    USAGE directoryOperation )

The 'objectIdentifierFirstComponentMatch' matching rule and the AttributeTypeDescription (1.3.6.1.4.1.1466.115.121.1.3) syntax are defined in [RFC4517].

4.2.3. 'matchingRules'​

This attribute holds definitions of matching rules.

  ( 2.5.21.4 NAME 'matchingRules'
    EQUALITY objectIdentifierFirstComponentMatch
    SYNTAX 1.3.6.1.4.1.1466.115.121.1.30
    USAGE directoryOperation )

The 'objectIdentifierFirstComponentMatch' matching rule and the MatchingRuleDescription (1.3.6.1.4.1.1466.115.121.1.30) syntax are defined in [RFC4517].

4.2.4 'matchingRuleUse'

This attribute holds definitions of matching rule uses.

  ( 2.5.21.8 NAME 'matchingRuleUse'
    EQUALITY objectIdentifierFirstComponentMatch
    SYNTAX 1.3.6.1.4.1.1466.115.121.1.31
    USAGE directoryOperation )

The 'objectIdentifierFirstComponentMatch' matching rule and the MatchingRuleUseDescription (1.3.6.1.4.1.1466.115.121.1.31) syntax are defined in [RFC4517].

4.2.5. 'ldapSyntaxes'​

This attribute holds definitions of LDAP syntaxes.

  ( 1.3.6.1.4.1.1466.101.120.16 NAME 'ldapSyntaxes'
    EQUALITY objectIdentifierFirstComponentMatch
    SYNTAX 1.3.6.1.4.1.1466.115.121.1.54
    USAGE directoryOperation )

The 'objectIdentifierFirstComponentMatch' matching rule and the SyntaxDescription (1.3.6.1.4.1.1466.115.121.1.54) syntax are defined in [RFC4517].

4.2.6. 'dITContentRules'​

This attribute lists DIT Content Rules that are present in the subschema.

  ( 2.5.21.2 NAME 'dITContentRules'
    EQUALITY objectIdentifierFirstComponentMatch
    SYNTAX 1.3.6.1.4.1.1466.115.121.1.16
    USAGE directoryOperation )

The 'objectIdentifierFirstComponentMatch' matching rule and the DITContentRuleDescription (1.3.6.1.4.1.1466.115.121.1.16) syntax are defined in [RFC4517].

4.2.7. 'dITStructureRules'​

This attribute lists DIT Structure Rules that are present in the subschema.

  ( 2.5.21.1 NAME 'dITStructureRules'
    EQUALITY integerFirstComponentMatch
    SYNTAX 1.3.6.1.4.1.1466.115.121.1.17
    USAGE directoryOperation )

The 'integerFirstComponentMatch' matching rule and the DITStructureRuleDescription (1.3.6.1.4.1.1466.115.121.1.17) syntax are defined in [RFC4517].

4.2.8 'nameForms'

This attribute lists Name Forms that are in force.

  ( 2.5.21.7 NAME 'nameForms'
    EQUALITY objectIdentifierFirstComponentMatch
    SYNTAX 1.3.6.1.4.1.1466.115.121.1.35
    USAGE directoryOperation )

The 'objectIdentifierFirstComponentMatch' matching rule and the NameFormDescription (1.3.6.1.4.1.1466.115.121.1.35) syntax are defined in [RFC4517].

4.3. 'extensibleObject' object class​

The 'extensibleObject' auxiliary object class allows entries that belong to it to hold any user attribute. The set of allowed attribute types of this object class is implicitly the set of all attribute types of userApplications usage.

  ( 1.3.6.1.4.1.1466.101.120.111 NAME 'extensibleObject'
    SUP top AUXILIARY )

The mandatory attributes of the other object classes of this entry are still required to be present, and any precluded attributes are still not allowed to be present.

4.4. Subschema Discovery​

To discover the DN of the subschema (sub)entry holding the subschema controlling a particular entry, a client reads that entry's 'subschemaSubentry' operational attribute. To read schema attributes from the subschema (sub)entry, clients MUST issue a Search operation [RFC4511] where baseObject is the DN of the subschema (sub)entry,

scope is baseObject, filter is "(objectClass=subschema)" [RFC4515], and the attributes field lists the names of the desired schema attributes (as they are operational). Note: the "(objectClass=subschema)" filter allows LDAP servers that gateway to X.500 to detect that subentry information is being requested.

Clients SHOULD NOT assume that a published subschema is complete, that the server supports all of the schema elements it publishes, or that the server does not support an unpublished element.