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.
6.4 CONCEPTUAL OVERVIEW
Revision Date: 5/16/2007 Page 35 of 55
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.
6.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 type’s 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>
Revision Date: 5/16/2007 Page 36 of 55
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.6 DIRECTORY ENTRIES
6.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>[email protected]</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.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
Revision Date: 5/16/2007 Page 37 of 55 <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.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.6.4 Multi-valued Attributes
Where an entry has multiple values for a particular attribute, that attr element has multiple value children.
Revision Date: 5/16/2007 Page 38 of 55 <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>[email protected]</dsml:value> <dsml:value>[email protected]</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.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> 6.7 DIRECTORY SCHEMA 6.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
Revision Date: 5/16/2007 Page 39 of 55
<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>
1. 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.
2. superior (XML attribute)
The URI Reference of class(es) from which this one is derived.
3. type (XML attribute)
One of structural, abstract or auxiliary.
4. obsolete (XML attribute)
One of true or false. Defaults to false.
5. name (child element)
The NAME of the object class.
6. description (child element)
The optional DESC of the object class.
7. object-identifier (child element)
The object identifier (OID) of the object class.
8. attribute (child element)
A directory attribute type that entries of this class may or must have.
9. ref (XML attribute on attribute element)
The URI Reference of the directory attribute type.
10.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 constrained for attributes) or is a reference.
Revision Date: 5/16/2007 Page 40 of 55
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> 1. 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.
2. superior (XML attribute)
The URI Reference of attribute type from which this one is derived.
3. obsolete (XML attribute)
One of true or false. Defaults to false.
4. single-value (XML attribute)
One of true or false. Defaults to false.
5. user-modification (XML attribute)
One of true or false. Defaults to true.
6. name (child element)
The NAME of the attribute type.
7. description (child element)
The optional DESC of the attribute type.
8. object-identifier (child element)
The object-identifier (OID) of the object class.
9. syntax (child element)
An OID indicating the allowed syntax of values of this attribute type.
Revision Date: 5/16/2007 Page 41 of 55
An OID indicating the equality matching rule.
12.ordering (child element)
An OID indicating the equality matching rule.
13.substring (child element)
An OID indicating the equality matching rule.
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 contained for attributes) or is a reference.
6.8 CONFORMANCE
In defining conformance, it is useful to divide DSML documents into four types:
1. Documents containing neither directory schema nor any references to an external schema.
2. Documents containing no directory schema but containing at least one reference to an external schema.
3. Documents containing only a directory schema.
4. 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 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.
6.9 XMLSCHEMA FOR DSML See http://www.dsml.org/1.0/dsml.xsd
Revision Date: 5/16/2007 Page 42 of 55
Revision Date: 5/16/2007 Page 44 of 55
<?xml version="1.0"?>
<!-- XML Schema Description for DSML --> <!-- Last updated: 1999-11-30 --> <schema targetNS="http://www.dsml.org/DSML" version="1.0" xmlns="http://www.w3.org/1999/09/24-xmlschema"> <!-- DATA TYPES --> <datatype name="true-false"> <basetype name="string"/> <enumeration> <literal>true</literal> <literal>false</literal> </enumeration> </datatype> <datatype name="oid"> <basetype name="string"/> </datatype> <datatype name="uri-ref"> <basetype name="string"/> </datatype> <datatype name="distinguished-name"> <basetype name="string"/> </datatype> <!-- DOCUMENT ELEMENT --> <element name="dsml"> <archetype>
<element ref="directory-schema" minOccurs="0"/> <element ref="directory-entries" minOccurs="0"/> <attribute name="complete" type="true-false"/> </archetype>
</element> <!-- SCHEMA -->
<element name="directory-schema"> <archetype>
<group order="choice" minOccurs="0" maxOccurs="*"> <element ref="class"/>
<element ref="attribute-type"/> </group>
</archetype> </element>
Revision Date: 5/16/2007 Page 45 of 55
<element name="object-identifier" type="oid"/> <element name="class">
<archetype>
<element ref="name" maxOccurs="*"/>
<element ref="description" minOccurs="0"/>
<element ref="object-identifier" minOccurs="0"/>
<element ref="attribute" minOccurs="0" maxOccurs="*"/> <attribute name="id" type="id" minOccurs="1"/>
<attribute name="sup" type="uri-ref"/>
<attribute name="obsolete" type="true-false" default="false"/> <attribute name="type" type="NCName" minOccurs="1">
<enumeration> <literal>structural</literal> <literal>abstract</literal> <literal>auxiliary</literal> </enumeration> </attribute> </archetype> </element> <element name="attribute"> <archetype content="empty">
<attribute name="ref" type="uri-ref" minOccurs="1"/>
<attribute name="required" type="true-false" minOccurs="1"/> </archetype>
</element>
<element name="attribute-type"> <archetype>
<element ref="name" maxOccurs="*"/>
<element ref="description" minOccurs="0"/>
<element ref="object-identifier" minOccurs="0"/> <element name="syntax" type="oid" minOccurs="0"/> <element name="equality" type="oid" minOccurs="0"/> <element name="ordering" type="oid" minOccurs="0"/> <element name="substring" type="oid" minOccurs="0"/> <attribute name="id" type="id" minOccurs="1"/>
<attribute name="sup" type="uri-ref"/>
<attribute name="obsolete" type="true-false" default="false"/> <attribute name="single-value" type="true-false" default="false"/> <attribute name="user-modification" type="true-false" default="true"/> </archetype>
</element>
<!-- ENTRIES -->
<element name="directory-entries"> <archetype>
<element ref="entry" minOccurs="0" maxOccurs="*"/> </archetype>
Revision Date: 5/16/2007 Page 46 of 55
<!-- minimum occur for objectclass and attr are zero to allow for an entry that only expresses objectclasses or non-objectclass directory attributes -->
<element ref="objectclass" minOccurs="0" maxOccurs="*"/> <element ref="attr" minOccurs="0" maxOccurs="*"/>
<attribute name="dn" type="distinguished-name" minOccurs="1"/> </archetype>
</element>
<element name="objectclass"> <archetype>
<attribute name="ref" type="uri-ref"/>
<element name="oc-value" maxOccurs="*" type="string"> <archetype>
<attribute name="ref" type="uri-ref"/> </archetype> </element> </archetype> </element> <element name="attr"> <archetype>
<element ref="value" maxOccurs="*"/>
<attribute name="name" type="string" minOccurs="1"/> <attribute name="ref" type="uri-ref"/>
</archetype> </element>
<element name="value" type="string"> <archetype>
<attribute name="encoding" type="string"/> </archetype>
</element> </schema>
Revision Date: 5/16/2007 Page 47 of 55
<!-- DTD for DSML --> <!-- Last updated: 1999-11-30 --> <!ENTITY % distinguished-name "CDATA">
<!ENTITY % uri-ref "CDATA"> <!-- [URI]#XPointer --> <!ENTITY % oid "#PCDATA">
<!ELEMENT dsml (directory-schema?,directory-entries?)> <!ATTLIST dsml
complete (true|false) "true" >
<!-- SCHEMA -->
<!ELEMENT directory-schema (class|attribute-type)*>
<!-- element types common to class and attribute-type -->