TOC 
Network Working GroupA.L. Newton
Internet-DraftVeriSign, Inc.
Expires: January 15, 2002July 17, 2001

XDAP IP Directory Schema
draft-newton-xdap-ipdir-01

Status of this Memo

This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts.

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."

The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt.

The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html.

This Internet-Draft will expire on January 15, 2002.

Copyright Notice

Copyright (C) The Internet Society (2001). All Rights Reserved.

Abstract

This document describes an XDAP directory namespace and schema for registered Internet address information. The schema extends the necessary query and result operations of XDAP to provide a functional equivalent of the whois command syntaxes and results often used by IP registries.


 TOC 

Table of Contents
 TOC 

1. Introduction

This document describes an Internet address directory using an XML Schema[4] derived from and using the XDAP[5] schema. The query and result types are similar in function to the whois commands and results often used by IP address registries today.

The schema given is this document is specified using the Extensible Markup Language (XML) 1.0 as described in [1], XML Schema notation as described in [3] and [4], and XML Namespaces as described in [2].

It is important to note that XML is case sensitive. XML specifications and examples provided in this document MUST be interpreted in the exact character case presented to develop a conforming implementation.


 TOC 

2. Document Terminology

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC2119[9].

The term "holder" is taken from the meaning described in [6]. However, the term as it is used in this document refers to an individual or organization with the right to use an IP network and not a domain name.


 TOC 

3. Schema Description

The schema for this directory namespace defines no <complexAuthentication> derivative. Applications of this namespace should rely on either the XDAP transport or <simpleAuthentication> for client authentication.

XDAP requires the derivation of both query and result elements by a directory namespace. These descriptions follow.

3.1 Query Derivatives

3.1.1 <lookupContact> Query

This is a simple named look up of a single contact. The contact is specified by the <handle> element.

3.1.2 <findContacts> Query

<findContacts> searches for contacts given search constraints. The <beginsWith> element MUST be present and specifies the beginning of the common name of the contact. The <endsWith> element is OPTIONAL and MUST contain the end of the common name of the contact.

The <type> element is OPTIONAL and SHOULD contain a recognized type of contact. Typically the values for this element denote multiplicity of the contact, such as "organization" or "person".

3.1.3 <lookupHost> Query

This is a simple named look up of a name server host. The host MUST be specified by one of the following elements:

3.1.4 <lookupNetwork> Query

This is a simple named look up of an IP network. The network MUST be specified by one of the following elements:

3.1.5 <lookupAutonomousSystem> Query

This is a simple named look up of an autonomous system. The system MUST be specified by one of the following elements:

3.2 Result Derivatives

3.2.1 <hostInfo> Result

The <hostInfo> element is the expected result of a <lookupHost> query. It contains elements for the fully qualified host name of the host, the IP address of the host, and a reference to the host contact.

The address elements contain the IP address of the name server, either IP v4 or IP v6, and an OPTIONAL reference to the network which contains the given address.

3.2.2 <networkInfo> Result

The <networkInfo> element is the expected result of a <lookupNetwork> query. It has the following child elements:

3.2.3 <autonomousSystemInfo> Result

The <autonomousSystemInfo> element is the expected result of a <lookupAutonomousSystem> query. It has the following children:

3.2.4 <contactInfo> Result

The <contactInfo> element is the expected result of a <lookupContact> query. The children that MUST be present are <handle>, containing a registry assigned unique identifier, and <commonName>, which holds the common name of the contact. The other children of this element are OPTIONAL and contain Internet, phone, and postal address information.

3.2.5 <contacts> Result

The <contacts> element is the expected result of a <findContacts> query. This element MAY have no children, if it is not empty the children MUST be <contactInfo> elements.

3.3 Global Types

Some of the global types defined by the schema specified in this document are expressed using regular expressions. The regular expressions used for these definitions do not fully represent every allowable syntax for the intended type, but meet a standard of reasonableness for the expression of the types.

3.4 Support for <xdap:lookupEntity>

The following types of named entities are recognized by the <lookupEntity> query of XDAP:


 TOC 

4. Formal XML Syntax

This IP address directory is specified in the XML Schema notation. The formal syntax presented here is a complete schema representation suitable for automated validation of an XML instance when combined with the formal schema syntax of XDAP. Due to document formatting restrictions, readers should note that the regular expressions expressed in this schema DO NOT contain whitespace within the quotes containing the regular expression. 

<?xml version="1.0"?>
<schema xmlns="http://www.w3.org/2001/XMLSchema"
        xmlns:ipdir="urn:iana:xmlns:ipdir1"
        xmlns:xdap="urn:iana:xmlns:xdap1"
        targetNamespace="urn:iana:xmlns:ipdir1"
        elementFormDefault="qualified" >

  <annotation>
    <documentation>
      IP address directory schema 
      derived from XDAP schema 
    </documentation>
  </annotation>

  <!--             -->
  <!-- Query types -->
  <!--             -->

  <complexType name="lookupContactType">
    <complexContent>
      <extension base="xdap:queryType">
        <sequence>
          <element name="handle" 
            type="ipdir:handleType" />
        </sequence>
      </extension>
    </complexContent>
  </complexType>

  <element name="lookupContact"
    type="ipdir:lookupContactType"
    substitutionGroup="xdap:query" />

  <complexType name="findContactsType">
    <complexContent>
      <extension base="xdap:queryType">
        <sequence>
          <element name="beginsWith"
            minOccurs="1" maxOccurs="1">
            <simpleType>
              <restriction base="token">
                <minLength value="3"/>
              </restriction>
            </simpleType>
          </element>
          <element name="endsWith"
            minOccurs="0" maxOccurs="1" >
            <simpleType>
              <restriction base="token">
                <minLength value="2"/>
              </restriction>
            </simpleType>
          </element>
          <element name="type"
            type="token"
            minOccurs="0" maxOccurs="1" />
        </sequence>
      </extension>
    </complexContent>
  </complexType>

  <element name="findContacts"
    type="ipdir:findContactsType"
    substitutionGroup="xdap:query" />

  <complexType name="lookupHostType">
    <complexContent>
      <extension base="xdap:queryType">
        <choice>
          <element name="handle" 
            type="ipdir:handleType" />
          <element name="hostName"
            type="ipdir:domainNameType" />
          <element name="ipV4Address"
            type="ipdir:dotQuadIPv4Type" />
          <element name="ipV6Address"
            type="ipdir:textIPv6AddressType" />
        </choice>
      </extension>
    </complexContent>
  </complexType>

  <element name="lookupHost"
    type="ipdir:lookupHostType"
    substitutionGroup="xdap:query" />

  <complexType name="lookupNetworkType">
    <complexContent>
      <extension base="xdap:queryType">
        <choice>
          <element name="ipV4Address"
            type="ipdir:dotQuadIPv4Type" />
          <element name="ipV6Address"
            type="ipdir:textIPv6AddressType" />
        </choice>
      </extension>
    </complexContent>
  </complexType>

  <element name="lookupNetwork"
    type="ipdir:lookupNetworkType"
    substitutionGroup="xdap:query" />

  <complexType name="lookupAutonomousSystemType">
    <complexContent>
      <extension base="xdap:queryType">
        <choice>
          <element name="number"
            type="positiveInteger" />
          <element name="handle"
            type="ipdir:handleType" />
        </choice>
      </extension>
    </complexContent>
  </complexType>

  <element name="lookupAutonomousSystem"
    type="ipdir:lookupAutonomousSystemType"
    substitutionGroup="xdap:query"      />

  <!--              -->
  <!-- Result types -->
  <!--              -->

  <complexType name="hostInfoType">
    <complexContent>
      <extension base="xdap:resultType">
        <sequence>
          <element name="hostName"
            type="ipdir:domainNameType" />
          <choice
            minOccurs="1" maxOccurs="unbounded" >
            <element name="ipV4">
              <complexType>
                <sequence>
                  <element name="ipV4Address"
                    type="ipdir:dotQuadIPv4Type" />
                  <element name="networkReference"
                    type="anyURI"
                    minOccurs="0" maxOccurs="1" />
                </sequence>
              </complexType>
            </element>
            <element name="ipV6">
              <complexType>
                <sequence>
                  <element name="ipV6Address"
                    type="ipdir:textIPv6AddressType" />
                  <element name="networkReference"
                    type="anyURI"
                    minOccurs="0" maxOccurs="1" />
                </sequence>
              </complexType>
            </element>
          </choice>
          <element name="contactReference"
            type="anyURI" />
        </sequence>
      </extension>
    </complexContent>
  </complexType>

  <element name="hostInfo"
    type="ipdir:hostInfoType"
    substitutionGroup="xdap:result" />

  <complexType name="networkInfoType">
    <complexContent>
      <extension base="xdap:resultType">
        <sequence>
          <element name="holderReference"
            type="anyURI"
            minOccurs="0" maxOccurs="1" />
          <element name="contactReference"
            type="anyURI"
            minOccurs="0" maxOccurs="1" />
          <element name="handle"
            type="ipdir:handleType" />
          <choice>
            <element name="ipV4">
              <complexType>
                <sequence>
                  <element name="startIPv4"
                    type="ipdir:dotQuadIPv4Type" />
                  <element name="endIPv4"
                    type="ipdir:dotQuadIPv4Type" />
                </sequence>
              </complexType>
            </element>
            <element name="ipV6">
              <complexType>
                <sequence>
                  <element name="startIPv6"
                    type="ipdir:textIPv6AddressType" />
                  <element name="endIPv6"
                    type="ipdir:textIPv6AddressType" />
                </sequence>
              </complexType>
            </element>
          </choice>
        </sequence>
      </extension>
    </complexContent>
  </complexType>

  <element name="networkInfo"
    type="ipdir:networkInfoType"
    substitutionGroup="xdap:result" />

  <complexType name="hostOrNetworkType">
    <complexContent>
      <extension base="xdap:resultType">
        <sequence>
          <element name="nameServerReference"
            type="anyURI" />
          <element name="networkReference"
            type="anyURI" />
        </sequence>
      </extension>
    </complexContent>
  </complexType>

  <element name="hostOrNetwork"
    type="ipdir:hostOrNetworkType"
    substitutionGroup="xdap:result" />

  <complexType name="autonomousSystemInfoType">
    <complexContent>
      <extension base="xdap:resultType">
        <sequence>
          <element name="holderReference"
            type="anyURI"
            minOccurs="0" maxOccurs="1" />
          <element name="contactReference"
            type="anyURI"
            minOccurs="0" maxOccurs="1" />
          <element name="handle"
            type="ipdir:handleType" />
          <element name="startNumber"
            type="positiveInteger" />
          <element name="endNumber"
            type="positiveInteger" />
        </sequence>
      </extension>
    </complexContent>
  </complexType>

  <element name="autonomousSystemInfo"
    type="ipdir:autonomousSystemInfoType"
    substitutionGroup="xdap:result" />

  <complexType name="contactInfoType">
    <complexContent>
      <extension base="xdap:resultType">
        <sequence>
          <element name="handle" 
            type="ipdir:handleType" 
            minOccurs="0" maxOccurs="1" />
          <element name="commonName"
            type="token" />
          <element name="organization"
            type="normalizedString"
            minOccurs="0" maxOccurs="1" />
          <element name="e-mail"
            type="normalizedString"
            minOccurs="0" maxOccurs="1" />
          <element name="address"
            type="string"
            minOccurs="0" maxOccurs="1" />
          <element name="city"
            type="string"
            minOccurs="0" maxOccurs="1" />
          <element name="region"
            type="string"
            minOccurs="0" maxOccurs="1" />
          <element name="postalCode"
            type="normalizedString"
            minOccurs="0" maxOccurs="1" />
          <element name="country"
            type="token"
            minOccurs="0" maxOccurs="1" />
          <element name="phone"
            type="normalizedString"
            minOccurs="0" maxOccurs="1" />
          <element name="fax"
            type="normalizedString"
            minOccurs="0" maxOccurs="1" />
        </sequence>
      </extension>
    </complexContent>
  </complexType>

  <element name="contactInfo"
    type="ipdir:contactInfoType"
    substitutionGroup="xdap:result" />

  <complexType name="contactsType">
    <complexContent>
      <extension base="xdap:resultType">
        <sequence>
          <element name="contactInfo"
            type="ipdir:contactInfoType"
            minOccurs="0" maxOccurs="unbounded" />
        </sequence>
      </extension>
    </complexContent>
  </complexType>

  <element name="contacts"
    type="ipdir:contactsType"
    substitutionGroup="xdap:result" />

  <!--              -->
  <!-- Global types -->
  <!--              -->

  <simpleType name="handleType">
    <restriction base="token">
      <pattern value="(host|org|person|role|net|as):[A-zA-Z0-9-]*" />
      <maxLength value="255" />
    </restriction>
  </simpleType>

  <simpleType name="dotQuadIPv4Type">
    <restriction base="string">
      <pattern value="([\d]{1,3}.){3}[\d]{1,3}" />
      <minLength value="7" />
      <maxLength value="15" />
    </restriction>
  </simpleType>

  <!-- does not support '::' -->
  <simpleType name="textIPv6AddressType">
    <restriction base="string">
      <pattern value="(([\dA-Fa-f]{1,4}:){7}[\dA-Fa-f]{1,4})(:([\d]{1,3}.){3}[\d]{1,3})?"/>
      <minLength value="16"/>
      <maxLength value="39"/>
    </restriction>
  </simpleType>

  <simpleType name="domainNameType">
    <restriction base="token">
      <pattern 
        value="([a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9]\.)*([a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9])?" />
      <maxLength value="255" />
    </restriction>
  </simpleType>

</schema>


 TOC 

5. Internationalization Considerations

The defining schema for this directory namespace is represented in XML, which provides native support for encoding information using the double-byte Unicode character set and its more compact representations including UTF-8. Compliant XML processors are required to understand both UTF-8 and raw Unicode character sets; XML also includes a provision for identifying other character sets through use of an "encoding" attribute in an <?xml?> processing instruction. The complete list of character set encoding identifiers is maintained by IANA and is described in ftp://ftp.isi.edu/in-notes/iana/assignments/character-sets and [7].


 TOC 

6. IANA Considerations

XML schemas require a URI for unique identification. Schemas MUST be registered to ensure URI uniqueness, but the IETF does not currently have a recommended repository for the registration of XML schemas. This document uses URNs to describe XML namespaces and XML schemas. IANA SHOULD maintain a registry of XML namespace and schema URI assignments. Per policies described in [8], URI assignment requests SHOULD be reviewed by a designated expert, and values SHOULD be assigned only as a result of standards action taken by the IESG.


 TOC 

7. Security Considerations

The schema given in this document describes no <complexAuthentication> derivatives nor specifies any authentication mechanism beyond that specified by [5].


 TOC 

References

[1] World Wide Web Consortium, "Extensible Markup Language (XML) 1.0", W3C XML, February 1998.
[2] World Wide Web Consortium, "Namespaces in XML", W3C XML Namespaces, January 1999.
[3] World Wide Web Consortium, "XML Schema Part 2: Datatypes", W3C XML Schema, October 2000.
[4] World Wide Web Consortium, "XML Schema Part 1: Structures", W3C XML Schema, October 2000.
[5] Newton, A., "eXtensible Directory Access Protocol", Internet Draft, a work in-progress., February 2001.
[6] Rader, R., "Domain Name Whois Data Element and Related Definitions", Internet Draft, a work in-progress., January 2001.
[7] Reynolds, J. and J. Postel, "ASSIGNED NUMBERS", RFC 1700, STD 2, October 1994.
[8] Narten, T. and H.T. Alvestrand, "Guidelines for Writing an IANA Considerations Section in RFCs", RFC 2434, BCP 26, October 1998.
[9] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", RFC 2119, BCP 14, March 1997.
 TOC 

Author's Address

  Andrew L. Newton
  VeriSign, Inc.
  505 Huntmar Park Drive
  Herndon, VA 20170
  USA
Phone:  +1 703 948 3382
EMail:  anewton@verisignlabs.com
URI:  http://www.verisignlabs.com/
 TOC 

Appendix A. An Example Request and Response

The following is an example of an XDAP request and response using this directory namespace.

This XML instance is a request to find contacts. 

<?xml version="1.0"?>
<xdap xmlns="urn:iana:xmlns:xdap1"
      xmlns:xdap="urn:iana:xmlns:xdap1"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="urn:iana:xmlns:xdap1 xdap.xsd" >

  <request>
    <directorySearch>
      <ipdir:findContacts
        xmlns:ipdir="urn:iana:xmlns:ipdir1"
        xsi:schemaLocation="urn:iana:xmlns:ipdir1 ipdir.xsd" >
        <ipdir:beginsWith>
          RIPE
        </ipdir:beginsWith>
        <ipdir:type>
          organization
        </ipdir:type>
      </ipdir:findContacts>
    </directorySearch>
  </request>

</xdap>

This XML instance is a response from ipdir-request.xml. 

<?xml version="1.0"?>
<xdap xmlns="urn:iana:xmlns:xdap1"
      xmlns:xdap="urn:iana:xmlns:xdap1"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="urn:iana:xmlns:xdap1 xdap.xsd" >

  <response>
    <directoryResult>
      <ipdir:contacts
        xmlns="urn:iana:xmlns:ipdir1"
        xmlns:ipdir="urn:iana:xmlns:ipdir1"
        xsi:schemaLocation="urn:iana:xmlns:ipdir1 ipdir.xsd" >
        <contactInfo>
          <handle>org:RIPE-NCC-ARIN</handle>
          <commonName>
            RIPE Network Coordination Centre
          </commonName>
          <organization>
            Reseaux IP European Network
            Co-ordination Centre
          </organization>
          <e-mail>
            nicdb@RIPE.NET
          </e-mail>
          <address>
            Singel 258
          </address>
          <city>
            Amsterdam
          </city>
          <postalCode>
            NL-1016 AB
          </postalCode>
          <country>
            NL
          </country>
          <phone>
            +31 20 535 4444
          </phone>
        </contactInfo>
      </ipdir:contacts>
    </directoryResult>
  </response>

</xdap>


 TOC 

Full Copyright Statement

Copyright (C) The Internet Society (2001). All Rights Reserved.

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English.

The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns.

This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Acknowledgement

Funding for the RFC editor function is currently provided by the Internet Society.