Reasons to Directory-Enable Existing Applications

Understanding and Deploying LDAP Directory Services > 7. Schema Design > Directory Schema Formats

<  BACK

CONTINUE  >

153021169001182127177100019128036004029190136140232051053055078214173171148163107250218

Directory Schema Formats

When reading vendor documentation or standards documents, or when working with directory service software, you will encounter several different formats that are used to describe a directory schema. It is useful to be able to read and understand all the popular schema formats. You will use this knowledge to choose a format to use when documenting the schemas for your directory service deployment. Three popular schema definition formats are described in this section.

The first schema format we describe, slapd.conf, is the one used throughout this book. The other two formats we describe (the ASN.1 and LDAPv3 formats) are included to help you read schema documentation that comes from other sources. You can safely skip over the description of the latter two formats if you want to move more quickly to the important task of designing schemas for your directory service.

The slapd.conf Schema Format

The schema format used in Netscape Directory Server's configuration files is based on the format used by the original University of Michigan Standalone LDAP server ( slapd ). We refer to this simple but widely used format as the slapd.conf schema format because slapd.conf is the traditional name for U-M's and Netscape's primary directory server configuration file. The format we describe here, the one supported by Netscape Directory Server 3.0 and 4.0, differs slightly from the format in the U-M LDAP 3.3 slapd release.

The slapd.conf schema format is based on two simple configuration file directives ”one for defining attribute types and one for defining object classes. These are described in the following sections.

slapd.conf Attribute Type Definitions

Each attribute type is defined using a line in the following form (all the items enclosed in square brackets are optional):

 attribute  NAME  [  ALIASES  ] [  OID  ]  SYNTAXID  [  OPTIONS  ] 

NAME is the attribute type name (e.g., cn ); ALIASES is an optional space-separated list of alternative names for the attribute (e.g., commonName ); OID is the object identifier for the attribute; and SYNTAXID is a short string that identifies a syntax and the associated matching rules that the directory server implementation supports.

OPTIONS is a space-separated list of one or more of these options: operational and single . The operational option indicates that the attribute is used by the directory service itself in a special way. The single option limits to one the number of attribute values that may be stored.

Note that the concept of aliases for attribute names is somewhat unique to the U-M and Netscape implementations and is included only for compatibility with directory clients that use longer names for attribute types. The six standard syntaxes supported by Netscape Directory Server 4.0 are shown in Table 7.2.

Table  7.2. Standard syntaxes supported by the Netscape Directory Server 4.0

slapd.conf Syntax ID	X.500 Equivalent	Description
cis	DirectoryString;caseIgnoreMatch	Text string; case ofletters and leading,trailing, and multiple spaces are ignored during comparisons.
ces	DirectoryString;caseExactMatch	Text string; case of letteris significant during comparisons; leading, trailing, and multiple spaces are ignored.
tel	PrintableString;telephoneNumberMatch	Text string that representsa phone number; like cis except space and hyphen characters are also ignored during comparisons.
int	Integer;integerMatch	Integer numbers ;comparisons follow rules for comparing integers.
dn	DistinguishedName;distinguishedNameMatch	Directory names(a pointer toanother entry); comparisons follow special rules for comparing distinguished names (DNs).
bin	OctetString;octetStringMatch	Arbitrary binary data;byte-by-byte comparisons.

Note that the Netscape Directory Server software allows additional syntaxes to be defined through the use of software plug-ins.

The following are a few examples of slapd.conf -style attribute type definitions:

 attribute cn commonName 2.5.4.3 cis attribute labeledURI 1.3.6.1.4.1.250.1.57 ces attribute seeAlso 2.5.4.34 dn attribute supportedLDAPVersion 1.3.6.1.4.1.1466.101.120.15 int attribute ntUserHomeDir 1.2.840.113556.1.4.44 cis single attribute passwordExpirationTime 2.16.840.1.113730.3.1.91 cis operational 

slapd.conf Object Class Definitions

Each object class is defined using a line in the following form (all the items enclosed in square brackets are optional):

 objectclass  NAME  [oid  OID  ] [superior  SUP  ] [requires  REQATTRS  ] [allows  ALLOWATTRS  ] 

NAME is the object class name, OID is the object identifier for the class, SUP is the class's superior or parent class, REQATTRS is a comma-separated list of required attribute types, and ALLOWATTRS is a comma-separated list of attribute types that are allowed to be included in entries that belong to the class. The order in which the attributes are listed following the requires and allows keywords is not significant.

Any attribute types used in the REQATTRS or ALLOWATTRS lists must be defined using attribute lines that precede the objectclass line. Note that if the first character on a slapd.conf line is a space character, it is logically considered part of the previous line. This feature is used to write object class definitions as a series of physical lines because the list of allowed attributes tends to make each definition quite long.

Listing 7.3 shows an example of a fairly simple slapd.conf-style object class definition.

Listing 7.3 The country object class in slapd.conf format

objectclass country oid 2.5.6.2 superior top requires c allows searchGuide, description

This is the definition for the standard country object class. It is derived from top , requires the c (country) attribute be included in all entries of the country class, and allows a searchGuide and a description to optionally be included. Remember that attributes may be used in many object classes. For example, the c attribute used here could also be included in an object class that describes a person.

Although the slapd.conf schema format has the slight disadvantage that it is tied to a specific family of directory server software products (i.e., those derived from the U-M LDAP software), it is simple, easy to understand, and easy to use for writing your own schema definitions.

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 are 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 a number 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 7.4 (all the items enclosed in square brackets are optional).

Listing 7.4 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, EQMATCHINGRULE identifies the rules that are used when testing two attribute values for equality, ORDMATCHINGRULE identifies the rules that are used when performing less-than -or-equal and greater-than-or-equal comparisons between values, SUBMATCHINGRULE identifies the rules that are 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 ub-name following the syntax identifier, which probably 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 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 (i.e., if it is derived from another 0attribute), the ASN.1 attribute definition will generally be in the form shown in Listing 7.5.

Listing 7.5 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 that ATNAME is derived from. The matching rules and any other information defined in the type's supertype need not be included. Listing 7.6 shows a simple example of this kind of attribute type definition.

Listing 7.6 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 very basic elements defined by the ASN.1 specification itself. The lines that start with two hyphens ( -- ) are simply comments included to aid humans who are reading the ASN.1 macros.

Some common ASN.1-based syntaxes are listed in Table 7.3.

Table  7.3. Common ASN.1-based syntaxes

Syntax	Description
DirectoryString	Text string; choice of several possible character sets. In LDAP, the character set is always UTF-8.
PrintableString	Text string; characters are from a restricted set that includes letters, digits, and a few punctuation characters (such as comma).
PostalAddress	Sequence of text strings that holds a postal (mailing) address.
BOOLEAN	Boolean values (TRUE or FALSE ).
INTEGER	Numbers; comparisons follow rules for comparing integers.
DistinguishedName	Directory names (a pointer to another entry).
OctetString	Arbitrary binary data.

DirectoryString is by far the most popular syntax used for attribute types. Some common ASN.1-based matching rules are listed in Table 7.4.

Table  7.4. Common ASN.1-based matching rules

Matching Rule	Description
caseIgnoreMatch	Case of letters and leading, trailing, and multiple spaces are ignored during comparisons.
caseExactMatch	Case of letters is significant during comparisons; leading, trailing, and multiple spaces are ignored.
telephoneNumberMatch	Like caseIgnoreMatch , except hyphen and space characters are also ignored during comparisons.
integerMatch	Comparisons follow the rules for comparing integers.
booleanMatch	Comparisons follow the rules for comparing Boolean values; only equality match is sup ported.
distinguishedNameMatch	Comparisons follow special rules for comparing DNs (number of relative distinguished names (RDNs) must be the same, each RDN must have the same number of values, and each type and value must match).
octetStringMatch	A binary (byte-by-byte) comparison if performed on values.

ASN.1 Object Class Definitions

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

Listing 7.7 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 it is derived from, and REQATTRS and ALLOWATTRS are the sets of required and allowed attribute types, respectively. If there are multiple attribute types in the REQATTRS or ALLOWATTRS sets, each is separated from its neighbor by a vertical bar character 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 7.8 shows a sample object class definition written using ASN.1.

Listing 7.8 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 }

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, like all 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.

As you can see, reading ASN.1 is complex and often involves peeling away several layers until you get to the information you need. This can be a tedious process because there is no way to tell in advance how many layers you will need to remove before you are done. ASN.1 is a general-purpose tool; unfortunately , general-purpose tools are usually harder to use than those designed to do one simple thing well. An advantage of ASN.1 schema descriptions is that they tend to be complete and precise.

The LDAPv3 Schema Format

Version 3 of the LDAP protocol requires that directory servers publish their supported schemas through LDAP itself. This allows directory client applications to programmatically retrieve the schema and adapt their behavior based on 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 it to the administrator.

Clients locate schema by reading the values of the subschemaSubentry operational attribute that is located in an LDAPv3 server's root DSE (directory server “specific entry) or by reading the same attribute from any 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 . In the Netscape Directory Server, for example, the global set of schema for the server can be found in the subschema entry named cn=schema .

The subschema object class allows these seven attribute types to be present:

• attributeTypes

• objectClasses

• matchingRules

• matchingRuleUse

• dITStructureRules

• nameForms

• ditContentRules

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

The LDAPv3 specification encourages servers to allow their schema to be modified over LDAP. If an implementation supports this, the attributes and objectclasses attributes of a subschema entry can be modified by a directory client (subject to access control restrictions, of course).

LDAPv3 Attribute Type Definitions

The attributeTypes attribute contains one value for each attribute supported by the server. Each value is as shown in Listing 7.9, broken up into multiple lines for clarity and with optional items in brackets.

Listing 7.9 The general form of LDAPv3 attributeTypes values

( ATOID NAME ATNAME [ DESC ATDESC ] [ SUP SUPOID ] [ EQUALITY EQMATCHOID ] [ ORDERING ORDMATCHOID ] [ SUBSTR SUBMATCHOID ] [ SYNTAX SYNOID ] [ SINGLE-VALUE] )

ATOID is the object identifier for the attribute, ATNAME is the attribute name, 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. Attributes are assumed to be multivalued unless the SINGLE-VALUE phrase is present. Parameters that are strings should be enclosed in single quotes.

The following uses the LDIF notation introduced in Chapter 3 to show how the attributeTypes value that describes the cn attribute might appear in an LDAPv3 server's subschema entry:

 attributetypes: ( 2.5.4.3 NAME 'cn' DESC 'commonName Standard Attribute' SYNTAX  1.3.6.1.4.1.1466.115.121.1.15 ) 

LDAPv3 Object Class Definitions

The objectClasses attribute type contains one value for each object class supported by the server. Listing 7.10 shows the general form for each value, broken up into multiple lines for clarity and with optional items in brackets.

Listing 7.10 The general form of LDAPv3 objectClasses values

( OCOID NAME OCNAME [ DESC OCDESC ] [ 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. Parameters that are strings should be enclosed in single quotes.

Here is how the objectClasses value that describes the standard person object class might appear in an LDAPv3 server's subschema entry:

 objectclasses: ( 2.5.6.6 NAME 'person' DESC 'Standard Person Object Class' SUP 'top' MUST  ( objectclass $ sn $ cn ) MAY ( description $ seealso $ telephonenumber $ userpassword) ) 

The LDAPv3 schema format is quite hard to read and is optimized for programmatic access rather than human readability.

Tip

We recommend that you use either the slapd.conf or ASN.1 schema format when designing your own directory's schema. The slapd.conf schema format is our favorite because it is the simplest and it can be used directly as server configuration information for some of the most popular LDAP server implementations.

Understanding and Deploying LDAP Directory Services,  2002 New Riders Publishing

<  BACK

CONTINUE  >

Index terms contained in this section

Abstract Syntax Notation One, see ASN.1
ASN.1 schema format
          defining attribute subtypes 2nd 3rd
          defining attributes 2nd 3rd
          defining object classes 2nd 3rd 4th
          matching rules 2nd
          syntaxes
ASN.1 schemas format
attributes
         defining
                    ASN.1 2nd 3rd
                    LDAPv3 schema format 2nd
                    slapd.conf 2nd 3rd 4th 5th 6th
         operational
                    subschemaSubentry
          subschema object class 2nd
         subtypes
                    defining in ASN.1 2nd 3rd
bin slapd.conf syntax ID
ces slapd.conf syntax ID
cis slapd.conf syntax ID
defining
         attribute subtypes
                    ASN.1 2nd 3rd
         attributes
                    ASN.1 2nd 3rd
                    LDAPv3 schema format 2nd
                    slapd.conf 2nd 3rd 4th 5th 6th
         object classes
                    ASN.1 2nd 3rd 4th
                    LDAPv3 schema format 2nd 3rd
                    slapd.conf 2nd
directories
         schemas
                    formats 2nd 3rd 4th 5th 6th 7th 8th 9th 10th 11th 12th 13th 14th 15th 16th 17th 18th 19th 20th 21st 22nd 23rd 24th 25th 26th 27th 28th 29th 30th 31st
dn slapd.conf syntax ID
formats
          schemas
                    ASN.1 2nd 3rd 4th 5th 6th 7th 8th 9th 10th 11th 12th 13th 14th
                    LDAPv3 2nd 3rd 4th 5th 6th 7th
                    slapd.conf 2nd 3rd 4th 5th 6th 7th 8th 9th
int slapd.conf syntax ID
LDAPv3
          schema format
                    attributeTypes attribute 2nd
                    objectClasses attribute 2nd 3rd
                    subschema object class
                    subschemaSubentry operational attribute
locality object class
          ASN.1 definition
matching rules
          ASN.1 schema format 2nd
Netscape Directory Server
          slapd.conf schema format
                    defining attributes 2nd 3rd 4th 5th 6th
                    defining object classes 2nd
object classes
         defining
                    ASN.1 2nd 3rd 4th
                    LDAPv3 schema format 2nd 3rd
                    slapd.conf 2nd
         locality
                    ASN.1 definition
          subschema
                    attributes 2nd
operational attributes
          subschemaSubentry
schemas
          formats
                    ASN.1 2nd 3rd 4th 5th 6th 7th 8th 9th 10th 11th 12th 13th 14th
                    LDAPv3 2nd 3rd 4th 5th 6th 7th
                    slapd.conf 2nd 3rd 4th 5th 6th 7th 8th 9th
slapd.conf schema format
          defining attributes 2nd 3rd 4th 5th 6th
          defining object classes 2nd
subschema object class
          attributes 2nd
subschemaSubentry operational attribute
subtypes
         attribute
                    defining in ASN.1 2nd 3rd
syntaxes
          ASN.1 schema format
          slapd.conf schema format 2nd 3rd
tel slapd.conf syntax ID

2002, O'Reilly & Associates, Inc.