Directory Services Markup Language (DSML)

1. Introduction

The Directory Services Markup Language, or DSML, provides a means for representing directory structural information as an XML document. The intent of DSML is to allow XML-based enterprise applications to leverage profile and resource information from a directory in their native environment. DSML allows XML and directories to work together and provides a common ground for all XML-based applications to make better use of directories.

DSML is intended to be a simple XML schema definition that will enable directories to publish basic profile information in the form of an XML document so that it can be easily shared via native Internet protocols (such as HTTP or SMTP), as well as used by other applications. The principal goal is to ensure that directories are able to make a growing breed of XML based applications directory aware.

It is not an initial goal of DSML to specify the attributes that all directories must contain, or the method with which the directory information is accessed from the directory. The expectation is that standard protocols (such as LDAP), proprietary access protocols (such as Novell's NDAP) and proprietary APIs (such as Microsoft's ADSI) could produce DSML documents as an optional output.

2. A Note on Ambiguous Terminology

Because this specification discusses both XML and directories, there is a danger of terminology from one domain being confused with that from the other. In particular, the words "attribute" and "schema" have meaning in both the XML and directory domains. For this reason, this specification always qualifies the word "attribute" as either XML attribute or a directory attribute and likewise with the word "schema".

3. The DSML Namespace URI

The vocabulary described in this specification is identified by the URI:

http://www.dsml.org/DSML

This is the DSML Namespace URI.

In this specification, the prefix "dsml" is used on XML elements to indicate that they belong to the DSML Namespace. The prefix (as with all XML Namespace prefixes) is arbitrary and any suitable prefix may be used (or the namespace declared as default). It is the URI which ultimate identifies the namespace, not the prefix.

4. Conceptual Overview

A DSML document describes either directory entries, a directory schema or both.

Each directory entry has a universally unique name called its distinguished name. A directory entry has a number of property-value pairs called directory attributes. Every directory entry is a member of a number of object classes. An entry's object classes constrain the directory attributes the entry may take. Such constraints are described in a directory schema which may be included in the same DSML document or may be in a separate document.

5. Top-level structure

The document element of DSML is of the type dsml which may have a child element of the type directory-entries. This element, in turn, has child elements of the type entry. The dsml element may also (if the document contains a directory schema) have a child element of the type directory-schema which, in turn, has child elements of the types class and attribute-type.

At the top-level, the structure of a DSML document is thus:

<dsml:dsml xmlns:dsml="http://www.dsml.org/DSML">
  <!-- a document with only directory entries -->
  <dsml:directory-entries>
    <dsml:entry dn="...">...</dsml:entry>
    <dsml:entry dn="...">...</dsml:entry>
    <dsml:entry dn="...">...</dsml:entry>
    ...
  </dsml:directory-entries>
</dsml:dsml>

<dsml:dsml xmlns:dsml="http://www.dsml.org/DSML">
  <!-- a document with only a directory schema -->
  <dsml:directory-schema>
    <dsml:class id="..." ...>...</dsml:class>
    <dsml:attribute-type id="..." ...>...</dsml:attribute-type>
    ...
  </dsml:directory-schema>
</dsml:dsml>

<dsml:dsml xmlns:dsml="http://www.dsml.org/DSML">
  <!-- a document with both -->
  <dsml:directory-schema>
    <dsml:class id="..." ...>...</dsml:class>
    <dsml:attribute-type id="..." ...>...</dsml:attribute-type>
  </dsml:directory-schema>
  <dsml:directory-entries>
    <dsml:entry dn="...">...</dsml:entry>
    <dsml:entry dn="...">...</dsml:entry>
    <dsml:entry dn="...">...</dsml:entry>
    ...
  </dsml:directory-entries>

<dsml:dsml>

The top-level element dsml takes an optional XML attribute complete. A value of true indicates that the entries under directory-entries contain no external references. Either all attribute-types and classes referenced are found in the directory-schema section of the document or there are no references at all. A value of false indicates that at least one reference is to an external DSML document containing a directory schema. The default value is true.

6. Directory Entries

6.1 The `entry` element type

Each entry represented in a DSML document is done so using an element of the type entry. The entry element contains elements representing the entry's directory attributes. The distinguished name of the entry is indicated by the XML attribute dn.

NOTE: This specification does not provide a canonical form for distinguished names. Because normalization and ordering can vary between producers of DSML, some form of canonicalization would need to be performed by a consumer of DSML before string matching the values of the XML attribute dn.

It was decided to express the distinguished name as an XML attribute rather than a child element because of its identifying characteristic.

<dsml:entry dn="uid=prabbit,ou=development,o=bowstreet,c=us">
  <dsml:objectclass>
    <dsml:oc-value>top</dsml:oc-value>
    <dsml:oc-value>person</dsml:oc-value>
    <dsml:oc-value>organizationalPerson</dsml:oc-value>
    <dsml:oc-value>inetOrgPerson</dsml:oc-value>
  </dsml:objectclass>
  <dsml:attr name="sn"><dsml:value>Rabbit</dsml:value></dsml:attr>
  <dsml:attr name="uid"><dsml:value>prabbit</dsml:value></dsml:attr>
  <dsml:attr name="mail"><dsml:value>prabbit@dsml.org</dsml:value></dsml:attr>
  <dsml:attr name="givenname"><dsml:value>Peter</dsml:value></dsml:attr>
  <dsml:attr name="cn"><dsml:value>Peter Rabbit</dsml:value></dsml:attr>

</dsml:entry>

6.2 Entry Object Class

The object classes of an entry are represented by oc-value child elements of an objectclass element. The content of each oc-value element indicates an object class to which the entry belongs. In the case where an object class has more than one name, only one name need be used. Both objectclass and oc-value have an optional XML attribute ref. An oc-value's ref is a URI Reference to a class element that defines the object class. An objectclass's ref is a URI Reference to an attribute-type defining the objectclass directory attribute. The latter would not often be used but is provided to allow for extension of the objectclass directory attribute.

<dsml:objectclass ref="#objectclass">
  <dsml:oc-value ref="#person">person</dsml:oc-value>
  <dsml:oc-value ref="#org-person">organizationalPerson</dsml:oc-value>
</dsml:objectclass>

6.3 Directory Attributes

Directory attributes (with the exception of "objectclass") are represented by an attr element. This element has a mandatory XML attribute name which indicates a name of the directory attribute. (A directory attribute may have more than one name, but only one need be expressed in the name attribute.)

The value or values of a directory attribute are expressed in child elements of the type value.

NOTE: the content of value is PCDATA and hence any XML markup (or characters that could be treated as markup, namely < or &) must be escaped via CDATA section, character reference or pre-defined entity.

Each attr element may have an optional ref XML attribute whose value is a URI reference (URI + XPointer) pointing to an attribute-type definition in a directory-schema in the same or different DSML document.

For example, if a DSML document with a directory-schema accessible at the URL http://www.bowstreet.com/schemata/physical-attributes.dsml has the attribute-type definition

<dsml:attribute-type id="eye-color">
  <dsml:name>eyecolor</dsml:name>
  <dsml:description>The color of the person's eyes</dsml:description>
  ...
</dsml:attribute-type>

then an entry in directory-entries might have a child element

<dsml:attr
    name="eyecolor"
    ref="http://www.bowstreet.com/schemata/physical-attributes.dsml#eye-color">
  <dsml:value>blue</dsml:value>
</dsml:attr>

6.4 Multi-valued Attributes

Where an entry has multiple values for a particular attribute, that attr element has multiple value children.

<dsml:entry dn="uid=prabbit,ou=development,o=bowstreet,c=us">
  <dsml:objectclass>
    <dsml:oc-value>top</dsml:oc-value>
    <dsml:oc-value>person</dsml:oc-value>
    <dsml:oc-value>organizationalPerson</dsml:oc-value>
    <dsml:oc-value>inetOrgPerson</dsml:oc-value>
  </dsml:objectclass>
  <dsml:attr name="sn"><dsml:value>Rabbit</dsml:value></dsml:attr>
  <dsml:attr name="uid"><dsml:value>prabbit</dsml:value></dsml:attr>
  <dsml:attr name="mail">
    <dsml:value>prabbit@dsml.org</dsml:value>
    <dsml:value>peterr@home.com</dsml:value>
  </dsml:attr>
  <dsml:attr name="givenname"><dsml:value>Peter</dsml:value></dsml:attr>
  <dsml:attr name="cn"><dsml:value>Peter Rabbit</dsml:value></dsml:attr>

</dsml:entry>

6.5 Binary Data

Directory attributes containing binary data are encoded using an encoding scheme identified by an XML attribute encoding on the value element. At present, DSML supports only base64 as a value, but the encoding XML attribute is included in order to enable support for other encoding schemes in the future.

NOTE: base64 encoding, as described in RFC 1521, allows for whitespace characters which are to be ignored by any decoding software. Furthermore, base64 encoding does not introduce < or & characters and therefore no additional encoding is necessary to include base64 in XML character data.

<dsml:attr name="cacertificate">
  <dsml:value encoding="base64">
    MIICJjCCAY+...
  </dsml:value>

</dsml:attr>

7. Directory Schema

7.1 Object Classes

Each directory entry has a number of object classes, indicated by elements of the type objectclass.

An object class is defined with a class element in a directory-schema. The class element takes an ID XML attribute id to make referencing easier.

The object class definition for the "person" object class might look like:

<dsml:class
    id="person"
    superior="#top"
    type="structural">
  <dsml:name>person</dsml:name>
  <dsml:description>...</dsml:description>
  <dsml:object-identifier>2.5.6.6</object-indentifier>
  <dsml:attribute ref="#sn" required="true"/>
  <dsml:attribute ref="#cn" required="true"/>
  <dsml:attribute ref="#userPassword" required="false"/>
  <dsml:attribute ref="#telephoneNumber" required="false"/>
  <dsml:attribute ref="#seeAlso" required="false"/>
  <dsml:attribute ref="#description" required="false"/>

</dsml:class>

id (XML attribute): A locally unique identifier for the object class. This enables the object class to be referenced across the Web, in particular from the ref XML attribute of an entry's objectclass or a subclass's superior XML attribute.
superior (XML attribute): The URI Reference of class(es) from which this one is derived.
type (XML attribute): One of structural, abstract or auxiliary.
obsolete (XML attribute): One of true or false. Defaults to false.
name (child element): The NAME of the object class.
description (child element): The optional DESC of the object class.
object-identifier (child element): The object identifier (OID) of the object class.
attribute (child element): A directory attribute type that entries of this class may or must have.
ref (XML attribute on attribute element): The URI Reference of the directory attribute type.
required (XML attribute on attribute element): One of true or false. Indicates whether entries of this class are required to have the directory attribute or not.

XML attributes were chosen in those cases where the information provides unique identification (using an ID attribute not only ensures uniqueness but allows for ease of reference via XPointer), is an enumeration (which, in a DTD, can only be contrained for attributes) or is a reference.

7.2 Attribute Type Definitions

Directory attribute types are defined in a similar way to object classes. For example:

<dsml:attribute-type
    id="cn"
    superior="...#name">
  <dsml:name>cn</dsml:name>
  <dsml:description>...</dsml:description>
  <dsml:object-identifier>2.5.4.3</dsml:object-identifier>
</dsml:attribute-type>

<dsml:attribute-type
    id="mail">
  <dsml:name>mail</dsml:name>
  <dsml:description>...</dsml:description>
  <dsml:object-identifier>0.9.2342.19200300.100.1.3</dsml:object-identifier>
  <dsml:syntax bound="256">0.9.2342.19200300.100.3.5</dsml:syntax>

</dsml:attribute-type>

id (XML attribute): A locally unique identifier for the attribute type. This enables the attribute type to be referenced across the Web, in particular from the ref XML attribute of an entry's attr or a derived directory attribute's superior XML attribute.
superior (XML attribute): The URI Reference of attribute type from which this one is derived.
obsolete (XML attribute): One of true or false. Defaults to false.
single-value (XML attribute): One of true or false. Defaults to false.
user-modification (XML attribute): One of true or false. Defaults to true.
name (child element): The NAME of the attribute type.
description (child element): The optional DESC of the attribute type.
object-identifier (child element): The object-identifier (OID) of the object class.
syntax (child element): An OID indicating the allowed syntax of values of this attribute type.
bound (XML attribute on syntax): The suggested minimum upper bound for the attribute type.
equality (child element): An OID indicating the equality matching rule.
ordering (child element): An OID indicating the equality matching rule.
substring (child element): An OID indicating the equality matching rule.

8. Conformance

In defining conformance, it is useful to divide DSML documents into four types:

Documents containing no directory schema nor any references to an external schema.
Documents containing no directory schema but containing at least one reference to an external schema.
Documents containing only a directory schema.
Documents containing both a directory schema and entries.

A producer of DSML must be able to produce documents of type 1. A producer of DSML may, in addition, be able to produce documents of types 2 thru 4.

A producer that can produce documents of type 1 is said to be a level 1 producer. A producer than can produce documents of all four types is said to be a level 2 producer.

Future specifications (see Appendix D) will provide a mechanism for specifying during a request to a level 2 producer, which type of document is to be returned.

A consumer of DSML must be able to handle all four document types although it need not be able to make use of the directory schema information (either local or externally referenced).

A consumer that can handle DSML documents of all four types is said to be a level 1 consumer. A consumer that can additionally make use of the directory schema information (either local or externally referenced) is said to be a level 2 consumer.

A. XML Schema for DSML

see dsml.xsd[viz., this file]

B. DTD for DSML

see dsml.dtd[viz., this file or this file]

C. Biztalk (XDR) Schema for DSML

see dsml.xdr[viz., this file]

D. Future Work

During the process of defining DSML 1.0, many work items were identified that did not fit into the agreed scope of the initial project. For a list of items explicitly deferred to future releases see http://www.dsml.org/1.0/futures.

E. Errata and Future compatability

As with any technical specification, as more companies begin to implement DSML, we may find omissions or errors in the current specification. As these changes are identified, they will be posted to an Errata document located at http://www.dsml.org/1.0/errata.

Every possible effort will be used to ensure that all future work will remain compatible with the 1.0 release of DSML. There is a possibility that new features, or additional work may require some changes to the XML schema as defined in this document. In this event, the future works will specify version management and compliance guidelines.