Authors: James Tauber (Bowstreet), Todd Hay (Bowstreet), Tom Beauvais (Bowstreet), Mike Burati (Bowstreet), Andrew Roberts (Bowstreet)
Contributors: Bill Gengler (IBM), Jay Unger (IBM), Mark Brown (Microsoft), Michael Mullany (Netscape/Sun Alliance), Leif Pedersen (Novell), Michael P. Mesaros (Oracle), David Saslav (Oracle)
Last updated: 1999-12-02
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.
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".
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.
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.
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.
entry element typeEach 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>
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>
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>
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>
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>
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)ref
XML attribute of an entry's objectclass or a
subclass's superior XML attribute.superior (XML attribute)type (XML attribute)structural, abstract or
auxiliary.obsolete (XML attribute)true or false. Defaults to
false.name (child element)description (child element)object-identifier (child element)attribute (child element)ref (XML attribute on attribute element)required (XML attribute on attribute
element)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.
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)ref
XML attribute of an entry's attr or a
derived directory attribute's superior XML attribute.superior (XML attribute)obsolete (XML attribute)true or false. Defaults to
false.single-value (XML attribute)true or false. Defaults to
false.user-modification (XML attribute)true or false. Defaults to
true.name (child element)description (child element)object-identifier (child element)syntax (child element)bound (XML attribute on syntax)equality (child element)ordering (child element)substring (child element)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.
In defining conformance, it is useful to divide DSML documents into four types:
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.
see dsml.xsd
see dsml.dtd
see dsml.xdr
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.
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.