Directory Schema Formats

When reading vendor documentation or standards documents, or when working with directory service software, you will encounter several different formats used to describe a directory schema. It is useful to be able to read and understand some popular schema formats. Two schema definition formats are described in this section.

The first schema format we describe, the LDAPv3 schema format, is the most popular one, and it is also the one used throughout this book. The other format we describe is the ASN.1 format, which is included to help you read schema documentation that happens to use it. In the first edition of this book, we described a third schema format: the slapd.conf schema format. That format is generally used only by older directory software such as Netscape Directory Server prior to release 6 and by OpenLDAP 1.x, so we do not describe it here.

The LDAPv3 Schema Format

Version 3 of the LDAP protocol requires that directory servers publish their supported schemas through LDAP itself, thereby allowing directory client applications to retrieve the schema programmatically and adapt their behavior to it. For example, a client that allows administrators to add new directory entries can query a directory server to find the complete list of structural object classes it supports and present that list to the administrator. The LDAPv3 schema format is described in RFC 2252, LDAPv3 Attribute Syntax Definitions .

Clients locate a set of schemas by reading the values of the subschemaSubentry operational attribute that is located in every directory entry. Values of the subschemaSubentry attribute are LDAP DNs that point to entries that belong to the subschema object class. Such entries are called subschema entries . Netscape Directory Server, for example, supports one global set of schemas for the server, which is stored in the subschema entry named cn=schema . Therefore every entry has a subschemaSubentry operational attribute that points to the cn=schema entry; that is, each has the value cn=schema .

The subschema object class allows the following seven regular attribute types to be present:

attributeTypes
objectClasses
matchingRules
matchingRuleUse
dITStructureRules
nameForms
dITContentRules

In addition, the following operational attribute type may be present in subschema subentries:

ldapSyntaxes

We discuss only the first two attributes ( attributeTypes and objectClasses ) because they are by far the most important and most widely used. For information on the rest, refer to the LDAPv3 Attribute Syntax Definitions document (RFC 2252).

The LDAPv3 specification encourages servers to allow their schemas to be modified over LDAP. If an implementation supports it, a directory client can modify the attributeTypes and objectClasses attributes of a subschema entry (subject to access control restrictions, of course).

Listing 8.3 shows how to use the Netscape ldapsearch command-line utility to retrieve a set of schemas. The first ldapsearch command finds the DN of the subschema entry that governs Babs Jensen's entry ( cn=schema ), and the second ldapsearch command retrieves the subschema entry itself. The entry data returned by the second command is truncated to save space.

Listing 8.3 Retrieving an LDAP Server's Schema

  ldapsearch -h ldap.example.com. -b "dc=example,dc=com" -s sub cn="Babs Jensen" uid  subschemaSubentry  version: 1 dn: uid=bjensen, ou=People, dc=example,dc=com uid: bjensen subschemaSubentry: cn=schema  ldapsearch -h ldap.example.com -b "cn=schema" -s base "objectclass=subschema"  objectClasses attributeTypes matchingRules matchingRuleUse dITStructureRules nameForms  dITContentRules ldapSyntaxes  version: 1 dn: cn=schema objectClasses: ( 2.5.6.0 NAME 'top' DESC 'Standard LDAP objectclass' ABSTRACT  MUST objectClass X-ORIGIN 'RFC 2256' ) objectClasses: ( 2.5.6.1 NAME 'alias' DESC 'Standard LDAP objectclass' SUP top   ABSTRACT MUST aliasedObjectName X-ORIGIN 'RFC 2256' ) objectClasses: ( 1.3.6.1.4.1.1466.101.120.111 NAME 'extensibleObject' DESC 'LD  APv3 extensible object' SUP top AUXILIARY X-ORIGIN 'RFC 2252' ) objectClasses: ( 2.5.6.2 NAME 'country' DESC 'Standard LDAP objectclass' SUP t  op STRUCTURAL MUST c MAY ( searchGuide $ description ) X-ORIGIN 'RFC 2256' ) objectClasses: ( 2.5.6.3 NAME 'locality' DESC 'Standard LDAP attribute type' S  UP top STRUCTURAL MAY ( description $ L $ searchGuide $ seeAlso $ st $ stree  t ) X-ORIGIN 'RFC 2256' ) ...

LDAPv3 Attribute Type Definitions

The attributeTypes attribute within a subschema entry of an LDAPv3-compliant server contains one value for each attribute supported by the server. Each value is as shown in Listing 8.4, broken up into multiple lines for clarity and with optional items in brackets.

Listing 8.4 The General Form of LDAPv3 `attributeTypes` Values

 (  ATOID  NAME  ATNAME  [ DESC  ATDESC  ] [ OBSOLETE ] [ SUP  SUPOID  ] [ EQUALITY  EQMATCHOID   ] [ ORDERING  ORDMATCHOID  ] [ SUBSTR  SUBMATCHOID  ] [ SYNTAX  SYNOID  ] [ SINGLE-VALUE ] [  COLLECTIVE ] [ NO-USER-MODIFICATION ] [ USAGE  ATUSAGE  ] )

ATOID is the object identifier for the attribute; ATNAME is the attribute name (which can be a list of names ); ATDESC is a text description of the attribute; SUPOID is the object identifier of the type it is derived from (if any); SYNOID is the object identifier of the attribute's syntax; and EQMATCHOID , ORDMATCHOID , and SUBMATCHOID are the object identifiers for the matching rules associated with the attribute type.

By default, attribute types are assumed to be multivalued unless the SINGLE-VALUE phrase is present. Attribute types that are marked with the OBSOLETE keyword cannot be used within new entries. Attribute types are shared among a set of entries if the COLLECTIVE keyword is present. If the NO-USER-MODIFICATION keyword is present, a normal user of the directory cannot modify the attribute type.

ATUSAGE indicates how attributes with this type are used in the directory service and must be one of the values shown in Table 8.4. If this parameter is omitted, the default value userApplications is in effect. All parameters that are strings should be enclosed in single quotes.

Each attribute type is represented by one value for the attributeTypes attribute within a subschema entry. Listing 8.5 shows how the standard cn and name attribute types would be described in the LDAPv3 schema format. The first attribute type has the OID 2.5.4.3 and two names ( cn and commonName ). It is a subtype of the name attribute type and therefore inherits other qualities from the attribute type called name . The second attribute type has the OID 2.5.4.41 and is called name . It has syntax DirectoryString with a length limit of 32,768 characters . The caseIgnore family of matching rules is specified (which means that the case of letters will be ignored when values are being compared).

Table 8.4. Attribute Usage Indicators

`ATUSAGE` Value	Description
`userApplications`	A regular attribute used by directory applications
`directoryOperation`	An operational attribute shared among replicas
`dSAOperation`	A server-specific operational attribute
`distributedOperation`	An operational attribute that supports distributed operations

Listing 8.5 The `cn` and `name` Attribute Types in the LDAPv3 Schema Format

 ( 2.5.4.3 NAME ( 'cn' 'commonName' ) DESC 'the name an object is commonly known by' SUP  name ) ( 2.5.4.41 NAME 'name' DESC 'the name supertype' EQUALITY caseIgnoreMatch SUBSTR  caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{32768} )

Listing 8.6 shows some additional examples of attribute type definitions in LDAPv3 format. Notice that the last two attribute type definitions include the additional keyword X-ORIGIN . The LDAPv3 format allows extended keywords to be used in attribute type and object class definitions; these must begin with " X- ". The Netscape products use X-ORIGIN to indicate the origin of a schema definition.

Listing 8.6 Additional Attribute Type Examples in the LDAPv3 Schema Format

 ( 1.3.6.1.4.1.250.1.57 NAME 'labeledURI' DESC 'Uniform Resource Identifier with optional  label' SYNTAX 1.3.6.1.4.1.1466.1.15.121.1.26 ) ( 2.5.4.34 NAME 'seeAlso' DESC 'DN pointer to a related entry' SUP distinguishedName  SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 ) ( 1.3.6.1.4.1.1466.101.120.15 NAME 'supportedLDAPVersion' DESC 'root DSE operational  attribute type' SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 X-ORIGIN 'RFC 2252' ) ( 2.16.840.1.113730.3.1.559 NAME 'nsMaxMailLists' DESC 'Limit for number of mailing lists  in a name space' SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE-VALUE X-ORIGIN 'Netscape  Delegated Administrator' )

LDAPv3 Object Class Definitions

The objectClasses attribute type within a subschema entry of an LDAPv3-compliant server contains one value for each object class supported by the server. Listing 8.7 shows the general form for each value, broken into multiple lines for clarity and with optional items in brackets.

Listing 8.7 The General Form of LDAPv3 `objectClasses` Values

 (  OCOID  NAME  OCNAME  [ DESC  OCDESC  ] [ OBSOLETE ] [ SUP  SUPOID  ] [  OCKIND  ] [ MUST  REQATSET   ] [ MAY  ALLOWATSET  ] )

OCOID is the object identifier for the class; OCNAME is the name of the object class; OCDESC is a text description of the class; SUPOID is the object identifier of the class it is derived from; OCKIND is ABSTRACT , STRUCTURAL , or AUXILIARY (the default is STRUCTURAL ); and REQATSET and ALLOWATSET are the names or OIDs of the required and allowed attribute types, respectively. The attribute sets are enclosed in parentheses, and each attribute type name is separated from the next with a dollar sign. Attribute types that are marked with the OBSOLETE keyword cannot be used within new entries. All parameters that are strings should be enclosed in single quotes.

Listing 8.8 shows how the standard person object class would appear in LDAPv3 schema format. The object identifier is 2.5.6.6 (a value assigned by the X.500 standards committee), the name of the class is person , the class is derived from the top abstract class, and the required and optional attribute types are as shown in the MUST and MAY lists. This is a structural class that is used as the primary object class for an entry.

Listing 8.8 The Standard `person` Object Class in LDAPv3 Format

 ( 2.5.6.6 NAME 'person' DESC 'Standard Person Object Class' SUP 'top' STRUCTURAL MUST (  objectclass $ sn $ cn ) MAY ( description $ seeAlso $ telephoneNumber $ userPassword ) )

Listing 8.9 shows two additional structural object classes: the inetOrgPerson object class from RFC 2798 and the organizationalPerson class from which it is derived (notice that organizationalPerson has person as its superior , so an entry with object class inetOrgPerson must obey the person rules as well).

Listing 8.9 The `inetOrgPerson` and `organizationalPerson` Object Classes in LDAPv3 Format

 ( 2.16.840.1.113730.3.2.2 NAME 'inetOrgPerson' DESC 'Extended organizational person  object class' SUP organizationalPerson STRUCTURAL MAY ( audio $ businessCategory $  carLicense $ departmentNumber $ displayName $ employeeNumber $ employeeType $ givenName $  homePhone $ homePostalAddress $ initials $ jpegPhoto $ labeledURI $ mail $ manager $  mobile $ o $ pager $ photo $ roomNumber $ secretary $ uid $ userCertificate $  x500uniqueIdentifier $ preferredLanguage $ userSMIMECertificate $ userPKCS12 ) ) ( 2.5.6.7 NAME 'organizationalPerson' DESC 'Standard organizational person objectclass'  SUP person STRUCTURAL MAY ( destinationIndicator $ facsimileTelephoneNumber $  internationaliSDNNumber $ L $ ou $ physicalDeliveryOfficeName $ postOfficeBox $  postalAddress $ postalCode $ preferredDeliveryMethod $ registeredAddress $ st $ street $  teletexTerminalIdentifier $ telexNumber $ title $ x121Address ) )

Finally, Listing 8.10 shows an example of a simple auxiliary object class. The labeledURIObject class is defined in RFC 2079 and can be added to any entry to allow a labeledURI attribute to be present in the entry, typically to allow a URL to be stored.

Listing 8.10 The `labeledURIObject` Class in LDAPv3 Format

 ( 1.3.6.1.4.1.250.3.15 NAME 'labeledURIObject' DESC 'object that contains the URI  attribute type' SUP top AUXILIARY MAY labeledURI X-ORIGIN 'RFC 2079' )

Although the LDAPv3 schema format is optimized for programmatic access rather than human readability, if you insert newline characters when composing a definition, it is fairly easy to read.

Tip

We recommend that you use the LDAPv3 schema format when designing your own directory's schema. The LDAPv3 format is used in most new RFCs and other standards documents, and it can be used directly as server configuration information for many of the most popular LDAP server implementations .

The ASN.1 Schema Format

Some of the LDAP and X.500 standards documents use Abstract Syntax Notation One (ASN.1) to document the schema they use, the elements of their protocols, and many other details. Although a complete discussion of ASN.1 is beyond the scope of this book, it is useful to learn to read and understand ASN.1-based schema definitions. If you are not interested in understanding ASN.1-based schema definitions, feel free to skip this entire section. You can always come back and read the material here if you run into ASN.1 when you're searching for schema elements to use for your own directory service.

At its most basic level, ASN.1 is a language that can be used to describe abstract types and values. Like most declarative programming languages, ASN.1 defines a series of simple types and allows them to be combined in various ways to build more complex descriptions. An ASN.1 definition, described in the next section, generally consists of interrelated definitions called ASN.1 macros .

ASN.1 Attribute Type Definitions

ASN.1 attribute type definitions are generally of the form shown in Listing 8.11 (all the items enclosed in square brackets are optional).

Listing 8.11 The General Form of an Attribute Type Definition in ASN.1

  ATNAME  ATTRIBUTE ::= {     WITH SYNTAX  SYNTAXNAME  {  BOUNDS  }     EQUALITY MATCHING RULE  EQMATCHINGRULE  [ ORDERING MATCHING RULE  ORDMATCHINGRULE  ]     [ SUBSTRINGS MATCHING RULE  SUBMATCHINGRULE  ]     [ SINGLEVALUED ]    ID  OID  }

ATNAME is the attribute type name, SYNTAXNAME identifies the attribute syntax, BOUNDS specifies restrictions on the size of the attribute values, EQMATCHINGRULE identifies the rules used when testing two attribute values for equality, ORDMATCHINGRULE identifies the rules used when performing less-than -or-equal and greater-than-or-equal comparisons between values, SUBMATCHINGRULE identifies the rules used when matching substrings to values, and OID is the object identifier for the attribute type.

Typically, SYNTAXNAME and all the matching-rule identifiers refer recursively to other ASN.1 macros. In most ASN.1 macros, the case of the letters used is not significant; upper- and lowercase letters may be used interchangeably. The following is a simple example:

 name ATTRIBUTE    ::= {     WITH SYNTAX DirectoryString { ub-name }     EQUALITY MATCHING RULE caseIgnoreMatch     SUBSTRINGS MATCHING RULE caseIgnoreSubstringsMatch     ID id-at-name }

This is the definition of the name attribute, which is really a supertype from which other naming attributes are derived. It has the syntax DirectoryString , which is one of the standard syntaxes LDAP uses. The parameter ub-name following the syntax identifier, which stands for "upper bound on name," is a limit on the size of the values for this attribute type. It is defined elsewhere as the integer value 64. Similarly, the OID id-at-name is defined as follows :

 id-at-name OBJECT IDENTIFIER ::= { id-at 41 }

This identifier expands to the complete OID 2.5.4.41 because id-at is defined somewhere else as 2.5.4 . The matching rules caseIgnoreMatch and caseIgnoreSubstringsMatch also have their own ASN.1 definitions, but we will not explore them in detail here.

If an attribute type is a subtype of another attribute type (that is, if it is derived from another attribute), the ASN.1 attribute definition will generally be in the form shown in Listing 8.12.

Listing 8.12 The General Form of a Subtyped Attribute Type in ASN.1

  ATNAME  ATTRIBUTE ::= {     SUBTYPE OF  SUPERTYPE  [ EQUALITY MATCHING RULE  EQMATCHINGRULE  ]     [ ORDERING MATCHING RULE  ORDMATCHINGRULE  ]     [ SUBSTRINGS MATCHING RULE  SUBMATCHINGRULE  ]     [ SINGLEVALUED ]     ID  OID  }

SUPERTYPE is the type from which ATNAME is derived. The matching rules and any other information defined in the type's supertype need not be included. Listing 8.13 shows a simple example of this kind of attribute type definition.

Listing 8.13 The ASN.1 Definition of the `cn` Attribute Type

 -- upper bound for cn: ub-common-name INTEGER ::= 64 -- OID branch for X.500 standard attribute types: id-at OBJECT IDENTIFIER ::= { 2.5.4 } -- OID for cn: id-at-commonName OBJECT IDENTIFIER ::= {id-at 3} -- the cn attribute type itself: commonName ATTRIBUTE    ::= {     SUBTYPE OF name     WITH SYNTAX DirectoryString {ub-common-name}     ID id-at-commonName }

Note that the definitions of ub-common-name and id-at-commonName were included because the commonName definition depends on these other ASN.1 elements. A complete ASN.1 schema definition must always define or import all the elements it references, except for some basic elements defined by the ASN.1 specification itself. The lines in Listing 8.13 that start with two hyphens ( -- ) are simply comments included to aid humans who are reading the ASN.1 macros.

ASN.1 Object Class Definitions

ASN.1-based object class definitions use the format shown in Listing 8.14.

Listing 8.14 The General Form of an ASN.1 Object Class Definition

  OCNAME  OBJECT-CLASS    ::= { SUBCLASS OF  {  SUPERCLASS  } MUST CONTAIN {  REQATTRS  } MAY CONTAIN  {  ALLOWATTRS  } ID  OID  }

OCNAME is the name of the object class, SUPERCLASS is the object class from which it is derived, and REQATTRS and ALLOWATTRS are the sets of required and allowed attribute types, respectively. If multiple attribute types are in the REQATTRS or ALLOWATTRS sets, each type is separated from its neighbor by a vertical bar in this manner:

 cn  sn

The order in which the attributes are listed is not significant. Sometimes other ASN.1 macros are used in place of an attribute type to refer to an entire set of attributes.

Listing 8.15 shows a sample object class definition written using ASN.1. This locality class, OID 2.5.6.3 , is used for entries that represent physical locations of various kinds, such as "the state of California" or "222-B Baker Street." It is a subclass of the class called top , which means that, as with all other structural object classes, the objectclass attribute is mandatory. The following attributes may optionally be included in locality entries: description , searchGuide , localityName , stateOrProvinceName , streetAddress , and seeAlso . Several of these attribute types are defined in the LocaleAttributeSet ASN.1 macro so that the set can easily be included in other object class definitions.

Listing 8.15 The ASN.1 Definition of the `locality` Object Class

 -- OID branch for X.500 standard object classes: id-oc OBJECT IDENTIFIER ::= 2.5.6 -- OID for locality object class: id-oc-locality OBJECT IDENTIFIER ::= {id-oc 3} -- a set of attributes that are useful for describing locales: LocaleAttributeSet ATTRIBUTE ::= {     localityName      stateOrProvinceName      streetAddress } -- an object class that represents a physical location locality OBJECT-CLASS ::= {     SUBCLASS OF    { top }     MAY CONTAIN    { description                       searchGuide                       LocaleAttributeSet                       seeAlso }     ID id-oc-locality }

As you can see, reading ASN.1 is complex and often involves peeling away several layers until you get to the information you need. The process can be tedious because there is no way to tell in advance how many layers you will need to remove before you're finished. ASN.1 is a general-purpose tool; unfortunately , general-purpose tools are usually more difficult to use than are those designed to do one simple thing well.