Network Working Group A. Newton
Internet-Draft
Request for Comments: 3981 VeriSign, Inc.
Expires: January 11, 2005
Category: Standards Track M. Sanz
DENIC eG
July 13,
December 2004
IRIS -
IRIS: The Internet Registry Information Service (IRIS) Core Protocol
draft-ietf-crisp-iris-core-07
Status of this This Memo
By submitting this Internet-Draft, I certify that any applicable
patent or other IPR claims of which I am aware have been disclosed,
and any of which I become aware will be disclosed, in accordance with
RFC 3668.
Internet-Drafts are working documents of
This document specifies an Internet standards track protocol for the
Internet Engineering
Task Force (IETF), its areas, community, and its working groups. Note that
other groups may also distribute working documents as
Internet-Drafts.
Internet-Drafts are draft documents valid requests discussion and suggestions for a maximum
improvements. Please refer to the current edition of six months the "Internet
Official Protocol Standards" (STD 1) for the standardization state
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 status of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt.
The list this protocol. Distribution of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.
This Internet-Draft will expire on January 11, 2005. this memo is unlimited.
Copyright Notice
Copyright (C) The Internet Society (2004). All Rights Reserved.
Abstract
This document describes an application layer client-server protocol
for a framework of representing to represent the query and result operations of the
information services of Internet registries. Specified in XML, the
Extensible Markup Language (XML), the protocol defines generic query
and result operations and a mechanism for extending these operations
for specific registry service needs.
Newton & Sanz Expires January 11, 2005 [Page 1]
Internet-Draft iris-core July 2004
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1 2
1.1. Use of XML . . . . . . . . . . . . . . . . . . . . . . . . 4
1.2 2
1.2. General Concepts . . . . . . . . . . . . . . . . . . . . . 4
1.3 3
1.3. Framework Layers . . . . . . . . . . . . . . . . . . . . . 5
1.4 4
1.4. Definitions . . . . . . . . . . . . . . . . . . . . . . . 5
1.5 4
1.5. Further Reading . . . . . . . . . . . . . . . . . . . . . 6 5
2. Document Terminology . . . . . . . . . . . . . . . . . . . . . 7 5
3. Protocol Identification . . . . . . . . . . . . . . . . . . . 8 5
4. Exchange Description . . . . . . . . . . . . . . . . . . . . . 9
4.1 6
4.1. Request Format . . . . . . . . . . . . . . . . . . . . . . 9
4.2 6
4.2. Response Format . . . . . . . . . . . . . . . . . . . . . 9
4.3 6
4.3. Extension Framework . . . . . . . . . . . . . . . . . . . 11
4.3.1 9
4.3.1. Derived Elements . . . . . . . . . . . . . . . . . . . 12
4.3.2 9
4.3.2. Registry Type Identifier Requirements . . . . . . . . 12
4.3.3 10
4.3.3. Entity Classes . . . . . . . . . . . . . . . . . . . . 13
4.3.4 10
4.3.4. Names of Entities . . . . . . . . . . . . . . . . . . 14
4.3.5 11
Newton & Sanz Standards Track [Page 1]
RFC 3981 IRIS-Core December 2004
4.3.5. References to Entities . . . . . . . . . . . . . . . . 14
4.3.6 11
4.3.6. Temporary Entities . . . . . . . . . . . . . . . . . . 15
4.3.7 12
4.3.7. <result> Derived Elements . . . . . . . . . . . . . . 15
4.3.8 13
4.3.8. <control> and <reaction> Elements . . . . . . . . . . 18
4.4 16
4.4. Relay Bags . . . . . . . . . . . . . . . . . . . . . . . . 20 18
5. Database Serialization . . . . . . . . . . . . . . . . . . . . 23 19
6. Formal XML Syntax . . . . . . . . . . . . . . . . . . . . . . 26 22
7. The IRIS URI . . . . . . . . . . . . . . . . . . . . . . . . . 42
7.1 37
7.1. URI Definition . . . . . . . . . . . . . . . . . . . . . . 42
7.2 37
7.2. Transport Specific Schemes . . . . . . . . . . . . . . . . 42
7.3 38
7.3. URI Resolution . . . . . . . . . . . . . . . . . . . . . . 43
7.3.1 38
7.3.1. Registry Dependent Resolution . . . . . . . . . . . . 43
7.3.2 38
7.3.2. Direct Resolution . . . . . . . . . . . . . . . . . . 43
7.3.3 39
7.3.3. Transport and Service Location . . . . . . . . . . . . 44
7.4 39
7.4. IRIS URI Examples . . . . . . . . . . . . . . . . . . . . 44 40
8. Checklists . . . . . . . . . . . . . . . . . . . . . . . . . . 46
8.1 41
8.1. Registry Definition Checklist . . . . . . . . . . . . . . 46
8.2 41
8.2. Transport Mapping Checklist . . . . . . . . . . . . . . . 46 42
9. Internationalization Considerations . . . . . . . . . . . . . 47 42
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . 48 . 43
11. Security Considerations . . . . . . . . . . . . . . . . . . 49 . 43
12. References . . . . . . . . . . . . . . . . . . . . . . . . . 50
12.1 . 43
12.1. Normative References . . . . . . . . . . . . . . . . . . . . 50
12.2 43
12.2. Informative References . . . . . . . . . . . . . . . . . . . 51
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 52 45
A. S-NAPTR and IRIS Uses . . . . . . . . . . . . . . . . . . . . 53
A.1 An 46
A.1. Examples of S-NAPTR with IRIS IRIS. . . . . . . . . . . . . . 53
A.2 46
A.2. Using S-NAPTR for Cohabitation . . . . . . . . . . . . . . 54 47
B. IRIS Design Philosophy . . . . . . . . . . . . . . . . . . . . 56
B.1 48
B.1. The Basic Premise . . . . . . . . . . . . . . . . . . . . 56
Newton & Sanz Expires January 11, 2005 [Page 2]
Internet-Draft iris-core July 2004
B.2 48
B.2. The Lure of a Universal Client . . . . . . . . . . . . . . 56
B.3 49
B.3. Server Considerations . . . . . . . . . . . . . . . . . . 57
B.4 49
B.4. Lookups, Searches, and Entity Classes . . . . . . . . . . 58
B.5 50
B.5. Entities References, Search Continuations, and Scope . . . 58 50
C. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 59
Intellectual Property and 51
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 51
Full Copyright Statements Statement . . . . . . . . 60
Newton & Sanz Expires January 11, 2005 [Page 3]
Internet-Draft iris-core July 2004 . . . . . . . . . . . . . 52
1. Introduction
The specification outlined in this document is based on the
functional requirements described in CRISP [17].
1.1
1.1. Use of XML
This document describes the specification for the Internet Registry
Information Service (IRIS), an XML text protocol with the purpose of
describing intended to describe
the query types and result types of various registry information
services. IRIS is specified by using the Extensible Markup Language
Newton & Sanz Standards Track [Page 2]
RFC 3981 IRIS-Core December 2004
(XML) 1.0 as described in [2], XML Schema notation as described in
[4] and [5], and XML Namespaces as described in [3].
1.2
1.2. General Concepts
Each kind of Internet registry is identified by a registry type. The
identifier for a registry type is a Uniform Resource Name (URN) used
within the XML instances to identify the XML schema that formally
describing
describes the set of queries, results, and entity classes allowed
within that type of registry.
The structure of these URNs makes no assumptions or restrictions on
the type types of registries they identify. Therefore, IRIS may support
multiple registry types of a disparate or similar nature; it is only
a matter of definition. For instance, a single registry type may be
defined for domain name registries while registries, and multiple registry types may
be defined for
the various IP address registries.
A registry information server may handle queries and serve results
for multiple registry types. Each registry type that a particular
registry operator serves is a registry service instance.
IRIS and the XML schema formally describing IRIS do not specify any
registry, registry identifier, or knowledge of a particular service
instance or set of instances. IRIS is a specification for a
framework with which these registries can be defined, used, and used and, in
some cases cases, interoperate. The framework merely specifies the
elements for registry identification and the elements which that must be
used to derive queries and results.
This framework allows a registry type to define its own structure for
naming, entities, queries, etc. etc., through the use of XML namespaces
and XML schemas (hence, a registry type MUST be identified by the
same URI that identifies its XML namespace). In order to To be compliant, a
registry type's specification must extend from this framework.
Newton & Sanz Expires January 11, 2005 [Page 4]
Internet-Draft iris-core July 2004
The framework does define defines certain structures that can be common to all
registry types, such as references to entities, search continuations, entity classes,
and more. entity classes. A registry type may declare its own definitions
for all of these, or it may mix its derived definitions with the base
definitions.
IRIS defines two types of referrals, referrals: an entity reference and a search
continuation. An entity reference indicates specific knowledge about
an individual entity, and a search continuation allows for distributed
searches. Both referrals may span differing registry types and
instances. No assumptions or specifications are made about the
roots, bases, or meshes of entities.
1.3
Newton & Sanz Standards Track [Page 3]
RFC 3981 IRIS-Core December 2004
1.3. Framework Layers
The IRIS framework can conceptually be thought of as having three layers.
-----------------------------
Registry-Specific |domain | address | etc... |
-----------------------------
Common-Registry | IRIS |
-----------------------------
Application-Transport | beep | iris-lwz | etc... |
-----------------------------
In this figure, "beep" refers to the Blocks Extensible Exchange
Protocol (BEEP) (see [20]) [20]), and "iris-lwz" refers to a theoritical theoretical
UDP binding using that uses compression.
The differing layers have the following responsibilities:
Registry-Specific :: Defines defines queries, results, and entity classes
of a specific type of registry. Each specific type of registry is
identified by a URN.
Common-Registry :: Defines defines base operations and semantics common to
all registry types such as search sets, result sets, referrals,
etc. and
referrals. It also defines the syntaxes for talking about
specific registry types.
Application-Transport :: Defines defines the mechanisms for
authentication, message passing, connection and session
management, etc. It also defines the URI syntax specific to the
application-transport mechanism.
1.4
1.4. Definitions
For clarity, the following definitions are supplied:
o registry type - -- A registry serving a specific function, such as a
domain registry or an address registry. Each type of registry is
assigned a URN.
Newton & Sanz Expires January 11, 2005 [Page 5]
Internet-Draft iris-core July 2004
o registry schema - -- The definition for a registry type specifying
the queries, results, and entity classes.
o authority - -- A reference to the server or set of servers
containing information.
o resolution method - -- The technique used to locate an authority.
o entity class - -- A group of entities with a common type or common
set of characteristics.
Newton & Sanz Standards Track [Page 4]
RFC 3981 IRIS-Core December 2004
o entity name - -- The identifier used to refer to a single entity
within an entity class.
o entity reference - -- A pointer to an entity composed of an
authority, an optional resolution method, a registry type, an
entity class, and an entity name. One type of entity reference is
the IRIS URI (defined in Section 7).
The terms "derivative", "derive", and "derivation" are used with the
same meaning for deriving one type of element from another as
specified in XML_SS [5].
1.5
1.5. Further Reading
Appendix B contains text answering the question, "Why IRIS?" IRIS?".
This document describes the structure at the core of IRIS. The
following documents describe the other aspects of IRIS relevant to
CRISP [17]: iris-beep [1], [1] and iris-dreg [18].
Newton & Sanz Expires January 11, 2005 [Page 6]
Internet-Draft iris-core July 2004
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 BCP 14, RFC 2119 [8].
Newton & Sanz Expires January 11, 2005 [Page 7]
Internet-Draft iris-core July 2004
3. Protocol Identification
The root element of all request XML instances MUST be <request>. The
root element of all response XML instances MUST be <response>. These
elements identify the start of the IRIS elements, the XML namespace
used as the identifier for IRIS, and optionally and, optionally, the location of the
schema. These elements and the associated closing tag MUST be
applied to all requests and responses sent by both clients and
servers.
The use of the schema location attribute, 'xsi:schemaLocation', attribute 'xsi:schemaLocation' is
OPTIONAL with respect to this specification, and IRIS implementations
MAY resolve it to retrieve the schema or they MAY use a locally cached
version of the schema.
Versioning of the IRIS protocol is the responsibility of the
application-transport layer but MUST be associated with the XML
namespace [3] URI representing IRIS. A change in this URI indicates
a change of the underlying schema and therefore and, therefore, a new version of
the protocol (and vice versa).
Newton & Sanz Expires January 11, 2005 Standards Track [Page 8]
Internet-Draft iris-core July 5]
RFC 3981 IRIS-Core December 2004
4. Exchange Description
This section describes the request and response exchanges of the
protocol. The descriptions contained within this section refer to
XML elements and attributes and their relation to the exchange of
data within the protocol. These descriptions also contain
specifications outside the scope of the formal XML syntax.
Therefore, this section will use terms defined by RFC 2119 [8] to
describe the specification outside the scope of the formal XML
syntax. While reading this section, please reference Section 6 for
needed
details on the formal XML syntax.
4.1
4.1. Request Format
A <request> element contains an optional <control> element and a set
of <searchSet> elements.
The <searchSet> elements enables enable a client to query a particular
registry type by using the URN identifying the registry type. This
can be found in one of its two children: <lookupEntity> and <query>.
The <lookupEntity> element describes the lookup of an entity in a
specific registry. This element has three attributes:
'registryType', 'entityClass', and 'entityName'. The 'registryType'
attribute contains the registry identifier for the registry type in
which the lookup operation is to will take place. The 'entityClass'
attribute contains the token identifying the index for which the
lookup operation is to will take place, and the 'entityName' attribute
contains the name of the entity to lookup. look up.
The <query> element is abstract and may not legally appear in an XML
instance. It provides the base type to be used by that registry schemas will use
to define derived query types. This derivation mechanism is
described in Section 4.3.
Each <searchSet> may also contain a <bag> element. When this element
appears as a child of <searchSet>, it MUST NOT contain the 'id'
attribute. For a description of the <bag> element, see Section 4.4.
The <control> element may contain one child element of any XML
namespace. This child element allows a client to signal to a server
the desire for
special states or processing. An example of one such <control> child
element may be found in Section 4.3.8.
4.2
4.2. Response Format
The <response> element contains an optional <reaction> element, a set
of <resultSet> elements, and an optional <bags> element.
Newton & Sanz Expires January 11, 2005 Standards Track [Page 9]
Internet-Draft iris-core July 6]
RFC 3981 IRIS-Core December 2004
The <resultSet> elements are responses to a <searchSet> request. The
contents of this element contain an <answer> element, an optional
<additional> element, and error elements elements, if applicable.
The children of the <answer> element are of the following types:
o <result> is an abstract element and may not be legally placed in
an XML instance. It provides the base type to be used by registry
schemas to define derived result types. This derivation mechanism
is described in Section 4.3.
o <entity> is an element specifying an entity reference. See
Section 4.3.5.
o The <searchContinuation> element specifies a query referral. Its
one child is any element derived from <query> (See (see Section 4.3.1).
To direct the query to a referent server, <searchContinuation> has
a mandatory 'authority' attribute and an optional 'resolution'
attribute. The <searchContinuation> element may also contain a
'bagRef' attribute. For a description of the 'bagRef' attribute,
see Section 4.4.
When following entity references and search continuations, clients
SHOULD only follow an <entity> or <searchContinuation> response once.
Failure to do so may result in the client process getting stuck in a
never-ending query loop loop, commonly known as a referral loop.
The <additional> element only contains <result> elements, as
described above. This element is provided to allow allows a server to indicate to a
client results that were not specifically queried but that are
related to the queried results, thus allowing enabling the client the
ability to properly display
this distinction to a user. user properly. The <additional> element use is
optional.
The following elements, representing which represent error conditions, may be
returned:
o <insufficientResources> - the -- The corresponding query requires
resources unobtainable by the server.
o <invalidName> - a -- A name given in a query is not syntactically
correct.
o <invalidSearch> - parameters -- Parameters of the corresponding query are not
semantically meaningful.
o <queryNotSupported> - the -- The corresponding query is not supported by
this server.
Newton & Sanz Standards Track [Page 7]
RFC 3981 IRIS-Core December 2004
o <limitExceeded> - the -- The corresponding query requires more resources
than allowed.
o <nameNotFound> - the -- The name given in a query does not match a known
entity.
o <permissionDenied> - the -- The authentication given does not allow
access to a specific result entry.
Newton & Sanz Expires January 11, 2005 [Page 10]
Internet-Draft iris-core July 2004
o <bagUnrecognized> - the -- The contents of a bag were unrecognized. See
Section 4.4.
o <bagUnacceptable> - the -- The contents of a bag were not and never will
be acceptable. See Section 4.4.
o <bagRefused> - the -- The contents of a bag were not acceptable at this
time. See Section 4.4.
o A derivative of <genericCode>, as described in Section 4.3.
The <resultSet> section is divided up into the <answer> and <additional>
sections in order to allow easier processing and navigation of the results by
a client. Servers MUST return the direct answers to queries in the
<answer> element, element and MAY return results in the <additional> element
for which a reference has been made to in the <answer> element. Results
in the <additional> element MUST have been referenced in the <answer>
<answer>, either as direct children of the <answer> element or as a
deeper descendant descendants of the <answer> element.
This serves two purposes. First, it may eliminate a requery by the
client for references contained in the <answer> element. Second, it
distinguishes between results that are a direct result of a query and
those that would have been returned had the client followed the
appropriate referrals, thus giving clients a hint as to hinting how to clients could process or
display the returned results. For instance, clients constructing
complex displays using with tree navigation widgets will know that results
in the <answer> element should all be directly beneath the root node
of the tree, while results in the <additional> element are to be leaf nodes
of those produced from the <answer> element.
A <reaction> element (child of <response>) is a response to a
<control> element, and provide provides a means for a server to advise a
client of the affect effect of a <control> element.
The <bags> element (child of <response>) is optional. It contains
<bag> elements, and the contents of each <bag> element is constitute one
element in any XML namespace. Each <bag> element has an 'id'
attribute, which is referenced by the 'bagRef' attribute of entity
Newton & Sanz Standards Track [Page 8]
RFC 3981 IRIS-Core December 2004
references (<entity>) and search continuations
(<searchContinuation>). See Section 4.4.
4.3
4.3. Extension Framework
Because the IRIS schema defines only one query type, no registry
structure, and only two stand-alone stand-
alone result types, and does not define a registry structure, it is
of limited use by itself. Extension of IRIS is accomplished through
the use of a base IRIS schema, as defined in XML_SD [4] and XML_SS
[5], and through extension of it by schemas constructed on top of
IRIS.
Newton & Sanz Expires January 11, 2005 [Page 11]
Internet-Draft iris-core July 2004
4.3.1
4.3.1. Derived Elements
The XML Schema definition of IRIS requires schemas of registry types
to derive element types from base types in the IRIS definition. The
registry schemas MUST derive elements for definition of to define typed queries and
results.
While the IRIS schema definition does not prohibit the derivation of
any elements, registry schemas SHOULD restrict the derivations to the
following types:
o <query> - as defined -- As defined, this element contains no content and has no
valid attributes. It is abstract and therefore only its
derivatives
of it appear in XML instances. Registry schemas derive from
this element to define the queries allowed.
o <result> - as defined -- As defined, this element contains no content and has
five valid attributes: 'authority', 'resolution' (optional),
'registryType', 'entityClass' 'entityClass', 'entityName', and
'temporaryReference' (optional, see Section 4.3.6). It is
abstract and therefore only its derivatives of it appear in XML
instances. Registry schemas derive from this element to define
results that may be returned from a query.
o <genericCode> - as -- As defined, this element is an instance of
<codeType>. It contains the optional elements <explanation> and
<language> to
<language>, which further describe the nature of the error.
o <entity> - identifies -- Identifies a reference to an entity. Registry schemas
SHOULD use elements derived from <entity>, <entity> but MAY use <entity>
directly. The advantage of deriving from <entity> vs. using it
directly direct use
is the chance to define the name of the element and to use that
name descriptively, descriptively -- for instance, as the role which the entity plays
with respect to another entity. See Section 4.3.5.
Newton & Sanz Standards Track [Page 9]
RFC 3981 IRIS-Core December 2004
o <seeAlso> - indicates -- Indicates a reference to an entity that has indirect
association with a parent element representing an entity. This
element is derived from the <entity> element (Section 4.3.5) element. 4.3.5).
Registry schemas MAY derive from this element or MAY use it
directly.
4.3.2
4.3.2. Registry Type Identifier Requirements
The identifier for a registry type and the XML namespace identifier
used by the XML Schema describing the registry MUST be the same.
These identifiers MUST be restricted to a URN [7] registered in the
'ns' class of the IANA registry governed by XML_URN [9]. These
identifiers are case insensitive.
This is a restriction on XML_NS [3], which specifies that an XML
namespace identifier is any valid URI [6].
These identifiers MAY be abbreviated to the part following the class
Newton & Sanz Expires January 11, 2005 [Page 12]
Internet-Draft iris-core July 2004
component and its separator of the URN. For example, the full URN
"urn:ietf:params:xml:ns:dreg1" may be abbreviated to "dreg1".
This
In use with IRIS, this abbreviation MUST NOT be used inside of XML
instances in use
with IRIS where which the XML Schema [4] specifies the use of a URI for
schema identification or where XML_NS [3] specifies the use of a URI
for XML namespace identification.
4.3.3
4.3.3. Entity Classes
Entity classes are provided in
IRIS provides entity classes to help avoid collisions with entity
names within any given registry type. Their specification in queries
also allows server implementations to quickly narrow search or lookup scopes
quickly to a single index.
For instance, the entity name "192.0.2.0" might refer to separate
entities in the "name-server" and "network" classes. The entity
"192.0.2.0" in the "name-server" class may refer to the name server
host that is also multi-homed by address 192.0.2.255 and known in DNS
as "ns.example.com", whereas the entity "192.0.2.0" in the "network"
class may refer to the network 192.0.2/30.
IRIS defines two default entity classes of "local" and "iris" "iris", which
MUST NOT be redefined. These entity classes MUST be valid in all
registry types.
The "local" class is reserved for entities defined locally by a
server operator and does not denote any particular type of entity. A
lookup in this entity class MAY result in an entity reference or
search continuation. For example, "iris:dreg1//example.com/local/
Newton & Sanz Standards Track [Page 10]
RFC 3981 IRIS-Core December 2004
myhosts" may result in a search continuation yielding the nameservers
for example.com.
The "iris" class is reserved for entities specific to a particular
service instance. It MUST contain the following entity names (see
Section 4.3.4: 4.3.4):
o "id" "id", which yields a result of <serviceIdentification> (see
Section 4.3.7.1).
o "limits" "limits", which yields a result of <limits> (see Section 4.3.7.2 ). 4.3.7.2).
This entity class MAY contain other locally defined entities as
well.
The names of entity classes in a registry schema are of type token token,
as defined by XML_SD [4]. Their case sensitivity MUST be defined by
the definition of the registry type. In general, they SHOULD be case
insensitive.
Newton & Sanz Expires January 11, 2005 [Page 13]
Internet-Draft iris-core July 2004
4.3.4
4.3.4. Names of Entities
The names of entities in a registry schema are of type token token, as
defined by XML_SD [4].
Names of entities SHOULD be unique within an instance of any
particular entity class within a registry. Two entities SHOULD NOT
have the same name, but a single entity MAY be known by multiple
names. In situations where a single name may result in two entities,
the registry schema SHOULD make allowances by defining result types
that contain entity references to both entities (i.e. (e.g., "example.com"
can refer to both the domain example.com and the host example.com).
However, this type of conflict SHOULD generally be avoided by the
proper use of entity classes.
The case sensitivity of entity names is dependent on the entity class
in which they reside. The definition of a registry type MUST specify
the case sensitivity for entity names. A registry type MAY define
the entity names of differing entity classes to have as having different case
sensitivity.
4.3.5
4.3.5. References to Entities
The element <entity> allows references to entities in result sets,
either as a direct child of <resultSet> or within a more complex
structure that derives deriving from <result>. The <entity> element is defined by
'entityType'. Registry schemas SHOULD define elements derived from
<entity> when referencing entities but may use the <entity> element
directly. Deriving a new element allows a registry schema to use the
Newton & Sanz Standards Track [Page 11]
RFC 3981 IRIS-Core December 2004
name of the new element as a role signifying to signify the relationship the referenced
entity has with the referrer. A derivative of <entity> MUST NOT be
used as a substitute when the <entity> element is declared (such as
in the <answer> section of the <resultSet>).
The <entity> element (and elements of type 'entityType') can have
child elements of <displayName> with an optional 'language'
attribute. These are provided so that servers may provide to clients
with a more human friendly meaning to human-friendly description of the entity reference. This
is often useful to users navigating referral structures.
The <entity> element (and its derivations) have the following
attributes:
o 'authority', 'resolution' (optional), 'registryType',
'entityClass', and 'entityName' - these -- These attributes specify where
the entity may be found.
o 'temporaryReference' - this -- This attribute is optional. See Section
4.3.6.
Newton & Sanz Expires January 11, 2005 [Page 14]
Internet-Draft iris-core July 2004
o 'referentType' - this -- This attribute contains the expected type of the
entity being referenced and may contain the word "ANY" or a
qualified XML name. Unlike the other attributes of <entity>, this
attributed
attribute is qualified and declared in the IRIS XML namespace.
Therefore it will also be qualified with the prefix associated
with the IRIS XML namespace (e.g. (e.g., 'iris:referentType'). This
allows clients to recognize entity references using an element
derived from <entity>.
o 'bagRef' - this -- This attribute is optional. If present, this attribute it must
contain an XML identifier to a <bag> element in the <bags> section
of the result set. For a description of the 'bagRef' attribute,
see Section 4.4.
4.3.6
4.3.6. Temporary Entities
There
Instances may exist instances where in which an entity reference needs to be
temporary. As an For example, a particular type of result may only have
one unique key. If that key contained contains semantic meaning that may not
be exposed to all users, a synthetic key will need have to be substituted.
As an additional example,
Furthermore, there may be times when data in the data store is not
normalized in the same manner as that expressed by the registry
schema. In the registry schema, objects of type A may reference
objects of type B. But in the data store, objects of type A may
contain objects of type B. Again, a synthetic key will need have to be
temporarily produced.
To
Newton & Sanz Standards Track [Page 12]
RFC 3981 IRIS-Core December 2004
To support such use cases, results and entity references can be
declared temporary by using the 'temporaryReference' attribute. This
attribute is of type boolean [4] and has a default value of "false".
It is optional for <result> derivatives and elements of type
'entityType'.
When this attribute is used, the entity reference data (i.e., (e.g.,
'entityClass', 'entityName', etc.) 'entityName') is only valid within the response in
which it appears and may not be consistent with subsequent responses.
A server MUST include the referent of any temporary entity reference
in the <additional> section of the same <resultSet>
4.3.7
4.3.7. <result> Derived Elements
The base IRIS framework does contain contains three elements directly derived from
the <result> element for use by any registry type.
4.3.7.1
4.3.7.1. <serviceIdentification>
An example of an a <serviceIdentification> result:
Newton & Sanz Expires January 11, 2005 [Page 15]
Internet-Draft iris-core July 2004
<serviceIdentification
authority="example.com" registryType="dreg1"
entityClass="iris"
entityName="id" >
<authorities>
<authority> example.com </authority>
<authority> example.net </authority>
<authority> example.org </authority>
</authorities>
<operatorName>
Ineternet
Internet Assigned Numbers Authority
</operatorName>
<eMail>
iana@iana.org
</eMail>
</serviceIdentification>
The <serviceIdentification> element is provided to allow IRIS clients
the ability
to reference IRIS service instances. It contains the following
elements:
o <authorities> - -- This element contains one or more <authority>
elements. Each <authority> element contains a URI authority
component for which the server has results. While Although a server MAY
only return a partial list of its authority areas areas, depending on
operator policy, it MUST return the authority for which the client
has requested.
Newton & Sanz Standards Track [Page 13]
RFC 3981 IRIS-Core December 2004
o <operatorName> - -- This element contains the name of the operator
of the server.
o <eMail> - -- These optional elements contain email addresses of the
operator of the service instance.
o <phone> - -- These optional elements contain phone numbers of the
operator of the service instance.
o <seeAlso> - -- See Section 4.3.1 for its definition.
4.3.7.2
4.3.7.2. <limits>
An example of a <limits> result:
Newton & Sanz Expires January 11, 2005 [Page 16]
Internet-Draft iris-core July 2004
<limits
authority="example.com" registryType="dreg1"
entityClass="iris" entityName="limits">
<totalQueries>
<perHour>2</perHour>
<perDay>15</perDay>
</totalQueries>
<totalResults>
<perHour>25</perHour>
<perDay>200</perDay>
</totalResults>
<totalSessions>
<perHour>2</perHour>
<perDay>15</perDay>
</totalSessions>
</limits>
The <limits> element provides a mechanism to allow allowing a server to inform
a client of the limits it may encounter from over use overuse of the service.
The contents describe the service limitations to a client at the
current level of access. The contents of this element are as
follows:
o <totalQueries> - -- This element describes the total number of
queries that the server will accept. The children of this element
indicate this number per a unit of time. The children are
<perSecond>, <perMinute>, <perHour>, and <perDay>. Each child
MUST only appear once as a child of <totalQueries>, but more than
one child MAY be present. For example, a server could indicate
that it will accept 15 queries a minute but only 60 queries a day.
Newton & Sanz Standards Track [Page 14]
RFC 3981 IRIS-Core December 2004
o <totalResults> - -- This element describes the total number of
results that the server will send to a client. The children of
this element indicate this number per unit of time in the same
manner as <totalQueries>.
o <totalSessions> - -- This element describes the total number of
sessions that the server will accept from a client. The children
of this element indicate this number per unit of time in the same
manner as <totalQueries>. The definition of a session is defined
the by application transport layer.
o <otherRestrictions> - -- This element describes other restrictions
that may only be expressible outside of the structured syntax of
the other child elements of <limits>. This element may have
optional <description> child elements, each with a mandatory
'language' attribute.
o <seeAlso> - -- These elements are provided to reference other
entities, such as a <simpleEntity> (Section 4.3.7.3) describing a
published policy. See <seeAlso> (Section 4.3.1).
All of these child elements are optional, and a server may express
Newton & Sanz Expires January 11, 2005 [Page 17]
Internet-Draft iris-core July 2004
that it has no limits by using a <limits> element with no content
(e.g.
(e.g., <limits authority=... />).
4.3.7.3
4.3.7.3. <simpleEntity>
An example of a <simpleEntity> result:
<simpleEntity
authority="example.com" registryType="dreg1"
entityClass="local"
entityName="notice" >
<property name="legal" language="en">
Example.com is reserved according to RFC 2606.
</property>
</simpleEntity>
The <simpleEntity> element is provided so that service operators may
make simple additions to other entities without the need for deriving entirely new
registry types. Its definition allows service operators to reference
it from other entities (using, for instance, a <seeAlso> element).
The <simpleEntity> is meant to represent name and value pairs of
strings, allowing each pair to be associated with a specific language qualifier,
qualifier and an optional URI pointing to more information.
Newton & Sanz Standards Track [Page 15]
RFC 3981 IRIS-Core December 2004
Clients may easily display such information as in a two-column table.
Uses needing
Applications using binary data or richer data structures are out of
scope for this element. When such usage scenarios arise, it is likely that a client
will likely need specific knowledge for handling to handle such data data, thus calling into question
the need for a new registry type.
4.3.8 type into question.
4.3.8. <control> and <reaction> Elements
The <control> (Section 4.1) and <reaction> (Section 4.2) elements
allow the client to request from the server special states for the
processing of queries. The intent of these elements is to allow
extensibility so that some jurisdictions may adopt policies for query
processing without requiring re-versioning of IRIS or any registry
type.
This document defines one control, <onlyCheckPermissions> <onlyCheckPermissions>, and its
requisite reaction, <standardReaction>, for compliance with CRISP
[17].
When a client sends an <onlyCheckPermissions> control, it is only
asking the server to only check to see if whether adequate permissions are
available to execute the queries in the associated request. A server
MUST respond to this control with a <standardReaction> element.
Newton & Sanz Expires January 11, 2005 [Page 18]
Internet-Draft iris-core July 2004
The <standardReaction> element provides a server with a standard
means to respond to controls (it may be used by other controls, but
that
this is left to their definition). It contains four children:
o <controlAccepted> - -- the processing or state needed by the control
has been accepted.
o <controlDenied> - -- the processing or state needed by the control
has been denied (a transient failure).
o <controlDisabled> - -- the processing or state needed by the control
cannot be activated (a permanent failure).
o <controlUnrecognized> - -- the control is not recognized (a
permanent failure).
If <onlyCheckPermissions> is rejected, then the server MUST return
all appropriate result sets (i.e. (i.e., for every search set in the
request), but all result sets MUST be empty of results and MUST
contain no errors (a reaction is not part of a result set and is
therefore not a result set error). This control applies to all
search sets or none at all, of them; therefore a server MUST issue a
rejection if <onlyCheckPermissions> cannot be accepted for all search
sets in a request.
Newton & Sanz Standards Track [Page 16]
RFC 3981 IRIS-Core December 2004
An example of an IRIS XML exchange using these elements: elements follows:
C: <?xml version="1.0"?>
C: <request xmlns="urn:ietf:params:xml:ns:iris1"
C: xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" >
C:
C: <control>
C: <onlyCheckPermissions />
C: </control>
C:
C: <searchSet>
C:
C: <lookupEntity
C: registryType="dreg1"
C: entityClass="local"
C: entityName="AUP" />
C:
C: </searchSet>
C:
C: </request>
S: <?xml version="1.0"?>
S: <response xmlns="urn:ietf:params:xml:ns:iris1"
S: xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" >
S:
S: <reaction>
S: <standardReaction>
S: <controlAccepted />
Newton & Sanz Expires January 11, 2005 [Page 19]
Internet-Draft iris-core July 2004
S: </standardReaction>
S: </reaction>
S:
S: <resultSet>
S: <answer>
S:
S: <simpleEntity
S: authority="example.com" registryType="dreg1"
S: entityClass="local" entityName="AUP" >
S: <property name="legal" language="en">
S: It is illegal to use information from this service
S: for the purposes of sending unsolicited bulk email.
S: </property>
S: </simpleEntity>
S:
S: </answer>
S: </resultSet>
S:
S: </response>
4.4
Newton & Sanz Standards Track [Page 17]
RFC 3981 IRIS-Core December 2004
4.4. Relay Bags
IRIS employs the use of bags to allow a server to relay information to a
referent server via the client. These bags are generated by the
queried server, passed to the client as opaque data, and then passed
to the referent server for processing. The contents of the bags are
not defined by IRIS, and the client MUST NOT make any assumptions
about the contents of a bag when relaying it from one server to
another.
When a server returns a result set to a client, the <response>
element may contain a <bags> child element. This child element
contains one or more <bag> elements. Each of these MUST contain an
'id' attribute containing the XML data type ID. Entity references
and search continuations that need have to specify a bag to be used when
they are followed MUST have a 'bagRef' attribute containing the XML
data type IDREF. See Section 4.2. This allows the response to only
specify a bag only once but allows each entity reference or search
continuation (in all result sets) to have a distinct bag bag, as needed.
When following an entity reference or search continuation that
specifies the use of a bag, the client MUST include the referenced
bag in the search set as a child of the <searchSet> element. See
Section 4.1.
See Section 4.2 for the list of errors a server may return to a
client when a bag is received. A server MUST NOT ignore a bag when
Newton & Sanz Expires January 11, 2005 [Page 20]
Internet-Draft iris-core July 2004
it is received. In case that a bag cannot be recognized or accepted, one
of the errors from Section 4.2 MUST be returned.
An example of an IRIS XML exchange using these elements: elements follows:
C: <?xml version="1.0"?>
C: <request xmlns="urn:ietf:params:xml:ns:iris1"
C: xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" >
C:
C: <searchSet>
C:
C: <bag>
C: <simpleBag xmlns="http://example.com/">
C: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
C: </simpleBag>
C: </bag>
C:
C: <lookupEntity
C: registryType="dreg1"
C: entityClass="local"
C: entityName="AUP" />
Newton & Sanz Standards Track [Page 18]
RFC 3981 IRIS-Core December 2004
C:
C: </searchSet>
C:
C: </request>
S: <?xml version="1.0"?>
S: <response xmlns="urn:ietf:params:xml:ns:iris1"
S: xmlns:iris="urn:ietf:params:xml:ns:iris1"
S: xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" >
S:
S: <resultSet>
S: <answer>
S:
S: <entity authority="example.com" bagRef="x1"
S: registryType="dreg1"
S: entityClass="local" entityName="AUP"
S: iris:referentType="ANY" >
S: <displayName language="en">
S: Acceptable Usage Policy
S: </displayName>
S: </entity>
S:
S: </answer>
S: </resultSet>
S:
S: <bags>
S:
Newton & Sanz Expires January 11, 2005 [Page 21]
Internet-Draft iris-core July 2004
S: <bag id="x1">
S: <simpleBag xmlns="http://example.com/">
S: AAAAB3NzaC1yc2EAAAABIwAAAIEA0ddD+W3Agl0Lel98G1r77fZ
S: </simpleBag>
S: </bag>
S:
S: </bags>
S: </response>
Newton & Sanz Expires January 11, 2005 [Page 22]
Internet-Draft iris-core July 2004
5. Database Serialization
This section describes a method for serializing IRIS registry
entities. The descriptions contained within this section refer to
XML elements and attributes and their relation to this serialization
process. These descriptions also contain specifications outside the
scope of the formal XML syntax. Therefore, this This section will use terms defined
by RFC 2119 [8] to describe the specification outside
the scope of the formal XML syntax. these. While reading this section,
please reference Section 6 for needed details on the formal XML
syntax.
Newton & Sanz Standards Track [Page 19]
RFC 3981 IRIS-Core December 2004
A database of IRIS entities can be serialized to file storage with
XML [2] by using the IRIS defined <serialization> element. This
element contains <result> element derivatives, derivatives and
<serializedReferral> elements.
Derivatives of the <result> element are entities. Servers loading
these entities MUST place the entity in the entity class classes specified
by the elements 'registryType', 'entityClass', and 'entityName'
attributes and in any entity class which classes the entity entities may apply according
to explicitly defined children of that element. For instance, if a
registry type has two entity classes of "foo" and "bar" and a <result>
derivative has the attributes entityClass="foo" and entityName="one"
and a child element <bar>two</bar>, the server is to enter that
entity into the entity class "foo" as the name "one" and into the
entity class "bar" as the name "two".
Servers loading entities as serialized derivatives of the <result>
element MAY translate the authority attribute. Servers will likely
need
have to do this if the authority for the entity has changed.
<serializedReferral> elements allow the serialization of explicit
entity references and search continuations. This element has a child
<source> element, element containing the 'authority', 'resolution' (optional),
'registryType', 'entityClass', and 'entityName' attributes. The
attributes of this element are to be used to signify the entity which that can be
referenced to yield this referral.
As mentioned above, there may be times when a server needs to
translate the authority attribute of a loaded entity.
Implementations must also beware of this need for referrals. During
deserialization, servers MUST change the authority attribute of a
referral (either <entity> or elements derived from <entity> or
<source> child of <serializedReferral>) to contain a valid authority
of the server if the serialized attribute is empty. During
serialization, servers and their related processes MUST leave the
authority attribute empty for referrals in which the referent is an
Newton & Sanz Expires January 11, 2005 [Page 23]
Internet-Draft iris-core July 2004
entity for which the server answers queries.
The following is an example of serialized IRIS. IRIS:
<iris:serialization
xmlns:iris="urn:ietf:params:xml:ns:iris1"
xmlns="urn:ietf:params:xml:ns:iris1"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
Newton & Sanz Standards Track [Page 20]
RFC 3981 IRIS-Core December 2004
<serviceIdentification
authority="iana.org" registryType="dreg1"
entityClass="iris"
entityName="id" >
<authorities>
<authority> iana.org </authority>
</authorities>
<operatorName>
Internet Assigned Numbers Authority
</operatorName>
<eMail>
dbarton@iana.org
</eMail>
<seeAlso
iris:referentType="iris:simpleEntity"
authority="iana.org" registryType="dreg1"
entityClass="local"
entityName="notice">
<displayName language="en">
Legal Notice
</displayName>
</seeAlso>
</serviceIdentification>
<serializedReferral>
<source
authority="example.com" registryType="dreg1"
entityClass="iris"
entityName="id"/>
<entity
iris:referentType="iris:serviceIdentification"
authority="iana.org" registryType="dreg1"
entityClass="iris" entityName="id"/>
</serializedReferral>
<simpleEntity
authority="iana.org" registryType="dreg1"
entityClass="local"
Newton & Sanz Expires January 11, 2005 [Page 24]
Internet-Draft iris-core July 2004
entityName="notice" >
<property name="legal" language="en">
Please use the net wisely!
</property>
</simpleEntity>
</iris:serialization>
Newton & Sanz Expires January 11, 2005 Standards Track [Page 25]
Internet-Draft iris-core July 21]
RFC 3981 IRIS-Core December 2004
6. Formal XML Syntax
IRIS is specified in XML Schema notation. The formal syntax
presented here is a complete schema representation of IRIS suitable
for automated validation of IRIS XML instances.
<?xml version="1.0"?>
<schema xmlns="http://www.w3.org/2001/XMLSchema"
xmlns:iris="urn:ietf:params:xml:ns:iris1"
targetNamespace="urn:ietf:params:xml:ns:iris1"
elementFormDefault="qualified" >
<annotation>
<documentation>
Internet Registry Information Service (IRIS) Schema v1
</documentation>
</annotation>
<!-- ========================================= -->
<!-- -->
<!-- The Transactions -->
<!-- -->
<!-- ========================================= -->
<element name="request">
<complexType>
<sequence>
<element
name="control"
type="iris:controlType"
minOccurs="0"
maxOccurs="1" />
<element
name="searchSet"
type="iris:searchSetType"
minOccurs="1"
maxOccurs="unbounded" />
</sequence>
</complexType>
</element>
<element name="response">
<complexType>
<sequence>
<element
name="reaction"
type="iris:reactionType"
minOccurs="0"
Newton & Sanz Expires January 11, 2005 Standards Track [Page 26]
Internet-Draft iris-core July 22]
RFC 3981 IRIS-Core December 2004
minOccurs="0"
maxOccurs="1" />
<element
name="resultSet"
type="iris:resultSetType"
minOccurs="1"
maxOccurs="unbounded" />
<element
name="bags"
type="iris:bagsType"
minOccurs="0"
maxOccurs="1" />
</sequence>
</complexType>
</element>
<!-- ========================================= -->
<!-- -->
<!-- Search Sets and Result Sets -->
<!-- -->
<!-- ========================================= -->
<complexType
name="searchSetType" >
<sequence>
<element
name="bag"
type="iris:bagType"
minOccurs="0"
maxOccurs="1" />
<choice>
<element
name="lookupEntity"
type="iris:lookupEntityType" />
<element
ref="iris:query" />
</choice>
</sequence>
</complexType>
<complexType
name="resultSetType" >
<sequence>
<element
name="answer"
minOccurs="1"
maxOccurs="1">
<complexType>
<sequence>
Newton & Sanz Expires January 11, 2005 Standards Track [Page 27]
Internet-Draft iris-core July 23]
RFC 3981 IRIS-Core December 2004
<sequence>
<element
ref="iris:result"
minOccurs="0"
maxOccurs="unbounded" />
<element
ref="iris:entity"
minOccurs="0"
maxOccurs="unbounded" />
<element
ref="iris:searchContinuation"
minOccurs="0"
maxOccurs="unbounded" />
</sequence>
</complexType>
</element>
<element
name="additional"
minOccurs="0"
maxOccurs="1">
<complexType>
<sequence>
<element
ref="iris:result"
minOccurs="1"
maxOccurs="unbounded" />
</sequence>
</complexType>
</element>
<choice
minOccurs="0"
maxOccurs="1" >
<element
name="insufficientResources"
type="iris:codeType" />
<element
name="invalidName"
type="iris:codeType" />
<element
name="invalidSearch"
type="iris:codeType" />
<element
name="queryNotSupported"
type="iris:codeType" />
<element
name="limitExceeded"
type="iris:codeType" />
<element
name="nameNotFound"
Newton & Sanz Expires January 11, 2005 Standards Track [Page 28]
Internet-Draft iris-core July 24]
RFC 3981 IRIS-Core December 2004
name="nameNotFound"
type="iris:codeType" />
<element
name="permissionDenied"
type="iris:codeType" />
<element
name="bagUnrecognized"
type="iris:codeType" />
<element
name="bagUnacceptable"
type="iris:codeType" />
<element
name="bagRefused"
type="iris:codeType" />
<element
ref="iris:genericCode"/>
</choice>
</sequence>
</complexType>
<!-- ========================================= -->
<!-- -->
<!-- Controls and Reactions -->
<!-- -->
<!-- ========================================= -->
<complexType
name="controlType">
<sequence>
<any
namespace="##any"
processContents="skip"
minOccurs="1"
maxOccurs="1" />
</sequence>
</complexType>
<complexType
name="reactionType">
<sequence>
<any
namespace="##any"
processContents="skip"
minOccurs="1"
maxOccurs="1" />
</sequence>
</complexType>
<!-- ========================================= -->
Newton & Sanz Expires January 11, 2005 Standards Track [Page 29]
Internet-Draft iris-core July 25]
RFC 3981 IRIS-Core December 2004
<!-- ========================================= -->
<!-- -->
<!-- Queries and Lookups -->
<!-- -->
<!-- ========================================= -->
<complexType
name="queryType" />
<element
name="query"
type="iris:queryType"
abstract="true" />
<complexType
name="lookupEntityType" >
<attribute
name="registryType"
type="anyURI"
use="required" />
<attribute
name="entityClass"
type="token"
use="required" />
<attribute
name="entityName"
type="token"
use="required" />
</complexType>
<!-- ========================================= -->
<!-- -->
<!-- Results -->
<!-- -->
<!-- ========================================= -->
<complexType
name="resultType">
<attribute
name="authority"
use="required"
type="token" />
<attribute
name="resolution"
type="token" />
<attribute
name="registryType"
use="required"
type="anyURI" />
Newton & Sanz Expires January 11, 2005 Standards Track [Page 30]
Internet-Draft iris-core July 26]
RFC 3981 IRIS-Core December 2004
type="anyURI" />
<attribute
name="entityClass"
use="required"
type="token" />
<attribute
name="entityName"
use="required"
type="token" />
<attribute
name="temporaryReference"
default="false"
type="boolean" />
</complexType>
<element
name="result"
type="iris:resultType"
abstract="true" />
<!-- ========================================= -->
<!-- -->
<!-- Errors -->
<!-- -->
<!-- ========================================= -->
<complexType
name="codeType">
<sequence
minOccurs="0"
maxOccurs="unbounded">
<element
name="explanation">
<complexType>
<simpleContent>
<extension
base="string">
<attribute
use="required"
name="language"
type="language" />
</extension>
</simpleContent>
</complexType>
</element>
</sequence>
</complexType>
<element
name="genericCode"
Newton & Sanz Expires January 11, 2005 Standards Track [Page 31]
Internet-Draft iris-core July 27]
RFC 3981 IRIS-Core December 2004
<element
name="genericCode"
type="iris:codeType"
abstract="true" />
<!-- ========================================= -->
<!-- -->
<!-- Entity References and -->
<!-- Search Continuations -->
<!-- -->
<!-- ========================================= -->
<complexType
name="entityType">
<sequence>
<element
name="displayName"
minOccurs="0"
maxOccurs="unbounded">
<complexType>
<simpleContent>
<extension
base="string">
<attribute
name="language"
use="required"
type="language" />
</extension>
</simpleContent>
</complexType>
</element>
</sequence>
<attribute
name="authority"
use="required"
type="token" />
<attribute
name="resolution"
type="token" />
<attribute
name="registryType"
use="required"
type="anyURI" />
<attribute
name="entityClass"
use="required"
type="token" />
<attribute
name="entityName"
use="required"
Newton & Sanz Expires January 11, 2005 Standards Track [Page 32]
Internet-Draft iris-core July 28]
RFC 3981 IRIS-Core December 2004
name="entityName"
use="required"
type="token" />
<attribute
name="referentType"
use="required"
form="qualified"
type="iris:referentTypeType" />
<attribute
name="temporaryReference"
default="false"
type="boolean" />
<attribute
name="bagRef"
type="IDREF" />
</complexType>
<element
name="entity"
type="iris:entityType" />
<simpleType
name="referentTypeType">
<union
memberTypes="QName iris:anyLiteralType" />
</simpleType>
<simpleType
name="anyLiteralType">
<restriction
base="string">
<enumeration
value="ANY" />
</restriction>
</simpleType>
<complexType
name="searchContinuationType">
<sequence>
<element ref="iris:query" />
</sequence>
<attribute
name="bagRef"
type="IDREF" />
<attribute
name="authority"
type="token"
use="required" />
<attribute
name="resolution"
Newton & Sanz Expires January 11, 2005 Standards Track [Page 33]
Internet-Draft iris-core July 29]
RFC 3981 IRIS-Core December 2004
<attribute
name="resolution"
type="token" />
</complexType>
<element
name="searchContinuation"
type="iris:searchContinuationType" />
<!-- ========================================= -->
<!-- -->
<!-- Bags -->
<!-- -->
<!-- ========================================= -->
<complexType
name="bagsType">
<sequence>
<element
name="bag"
minOccurs="1"
maxOccurs="unbounded">
<complexType>
<complexContent>
<extension
base="iris:bagType">
<attribute
use="required"
name="id"
type="ID" />
</extension>
</complexContent>
</complexType>
</element>
</sequence>
</complexType>
<complexType
name="bagType">
<sequence>
<any
namespace="##any"
processContents="skip"
minOccurs="1"
maxOccurs="1" />
</sequence>
</complexType>
Newton & Sanz Expires January 11, 2005 [Page 34]
Internet-Draft iris-core July 2004
<!-- ========================================= -->
<!-- -->
<!-- Derived Results for use with all -->
Newton & Sanz Standards Track [Page 30]
RFC 3981 IRIS-Core December 2004
<!-- registry types. -->
<!-- -->
<!-- ========================================= -->
<!-- -->
<!-- See Also -->
<!-- -->
<element
name="seeAlso"
type="iris:entityType" />
<!-- -->
<!-- Service Identification -->
<!-- -->
<complexType
name="serviceIdentificationType">
<complexContent>
<extension
base="iris:resultType">
<sequence>
<element
name="authorities"
minOccurs="1"
maxOccurs="1">
<complexType>
<sequence>
<element
name="authority"
type="token"
minOccurs="1"
maxOccurs="unbounded" />
</sequence>
</complexType>
</element>
<element
name="operatorName"
type="string"
minOccurs="0"
maxOccurs="1" />
<element
name="eMail"
type="string"
minOccurs="0"
maxOccurs="unbounded" />
<element
name="phone"
Newton & Sanz Expires January 11, 2005 Standards Track [Page 35]
Internet-Draft iris-core July 31]
RFC 3981 IRIS-Core December 2004
maxOccurs="unbounded" />
<element
name="phone"
type="string"
minOccurs="0"
maxOccurs="unbounded" />
<element
ref="iris:seeAlso"
minOccurs="0"
maxOccurs="unbounded" />
</sequence>
</extension>
</complexContent>
</complexType>
<element
name="serviceIdentification"
type="iris:serviceIdentificationType"
substitutionGroup="iris:result" />
<!-- -->
<!-- Limits -->
<!-- -->
<complexType
name="limitsType">
<complexContent>
<extension
base="iris:resultType">
<sequence>
<element
name="totalQueries"
minOccurs="0"
maxOccurs="1" >
<complexType>
<group
ref="iris:timeLimitsGroup"
minOccurs="1"
maxOccurs="4" />
</complexType>
</element>
<element
name="totalResults"
minOccurs="0"
maxOccurs="1" >
<complexType>
<group
ref="iris:timeLimitsGroup"
minOccurs="1"
maxOccurs="4" />
</complexType>
Newton & Sanz Expires January 11, 2005 Standards Track [Page 36]
Internet-Draft iris-core July 32]
RFC 3981 IRIS-Core December 2004
minOccurs="1"
maxOccurs="4" />
</complexType>
</element>
<element
name="totalSessions"
minOccurs="0"
maxOccurs="1" >
<complexType>
<group
ref="iris:timeLimitsGroup"
minOccurs="1"
maxOccurs="4" />
</complexType>
</element>
<element
name="otherRestrictions"
minOccurs="0"
maxOccurs="1">
<complexType>
<sequence>
<element
name="description"
minOccurs="0"
maxOccurs="unbounded">
<complexType>
<simpleContent>
<extension
base="string">
<attribute
name="language"
type="language"
use="required" />
</extension>
</simpleContent>
</complexType>
</element>
</sequence>
</complexType>
</element>
<element
ref="iris:seeAlso"
minOccurs="0"
maxOccurs="unbounded" />
</sequence>
</extension>
</complexContent>
</complexType>
<element
name="limits"
type="iris:limitsType"
Newton & Sanz Expires January 11, 2005 Standards Track [Page 37]
Internet-Draft iris-core July 33]
RFC 3981 IRIS-Core December 2004
<element
name="limits"
type="iris:limitsType"
substitutionGroup="iris:result" />
<group
name="timeLimitsGroup">
<choice>
<element
name="perSecond"
type="nonNegativeInteger" />
<element
name="perMinute"
type="nonNegativeInteger" />
<element
name="perHour"
type="nonNegativeInteger" />
<element
name="perDay"
type="nonNegativeInteger" />
</choice>
</group>
<!-- -->
<!-- Simple Entity -->
<!-- -->
<complexType
name="simpleEntityType">
<complexContent>
<extension
base="iris:resultType">
<sequence>
<element
name="property"
minOccurs="1"
maxOccurs="unbounded">
<complexType>
<simpleContent>
<extension
base="string">
<attribute
name="name"
type="string"
use="required" />
<attribute
name="language"
type="language"
use="required" />
<attribute
name="uri"
Newton & Sanz Expires January 11, 2005 Standards Track [Page 38]
Internet-Draft iris-core July 34]
RFC 3981 IRIS-Core December 2004
use="required" />
<attribute
name="uri"
type="anyURI" />
</extension>
</simpleContent>
</complexType>
</element>
</sequence>
</extension>
</complexContent>
</complexType>
<element
name="simpleEntity"
type="iris:simpleEntityType"
substitutionGroup="iris:result" />
<!-- ========================================= -->
<!-- -->
<!-- Derived Controls and Reactions -->
<!-- -->
<!-- ========================================= -->
<!-- -->
<!-- Only Check Permissions -->
<!-- -->
<element
name="onlyCheckPermissions" >
<complexType />
</element>
<!-- -->
<!-- Standard Reaction -->
<!-- -->
<element
name="standardReaction" >
<complexType>
<choice>
<element
name="controlAccepted">
<complexType/>
</element>
<element
name="controlDenied">
<complexType/>
</element>
<element
name="controlDisabled">
Newton & Sanz Expires January 11, 2005 Standards Track [Page 39]
Internet-Draft iris-core July 35]
RFC 3981 IRIS-Core December 2004
</element>
<element
name="controlDisabled">
<complexType/>
</element>
<element
name="controlUnrecognized">
<complexType/>
</element>
</choice>
</complexType>
</element>
<!-- ========================================= -->
<!-- -->
<!-- Serialization -->
<!-- -->
<!-- ========================================= -->
<complexType
name="serializedReferralType">
<sequence>
<element name="source">
<complexType>
<attribute
name="authority"
use="required"
type="token" />
<attribute
name="resolution"
type="token" />
<attribute
name="registryType"
type="anyURI"
use="required" />
<attribute
name="entityClass"
type="token"
use="required" />
<attribute
name="entityName"
type="token"
use="required" />
</complexType>
</element>
<choice>
<element
ref="iris:searchContinuation" />
<element
ref="iris:entity" />
</choice>
Newton & Sanz Expires January 11, 2005 Standards Track [Page 40]
Internet-Draft iris-core July 36]
RFC 3981 IRIS-Core December 2004
<element
ref="iris:entity" />
</choice>
</sequence>
</complexType>
<element
name="serialization">
<complexType>
<choice
minOccurs="1"
maxOccurs="unbounded">
<element
ref="iris:result" />
<element
name="serializedReferral"
type="iris:serializedReferralType" />
</choice>
</complexType>
</element>
</schema>
Figure 8
Newton & Sanz Expires January 11, 2005 [Page 41]
Internet-Draft iris-core July 2004
7. The IRIS URI
The IRIS URI has a very rigid structure but is flexible in how it may
be used. Its structure is rigid in that all structure. All IRIS URIs have the same
fields and all look similar to users.
They
But the IRIS URIs are flexible because they allow different methods
to be employed to find servers and they allow the use of multiple
transports (with BEEP being the default).
7.1
7.1. URI Definition
An IRIS URI [6] has the following general syntax.
iris:<registry>/<resolution>/<authority>/<class>/<name>
The full ABNF [11] follows, with certain values included from RFC
2396 [6] and RFC 2732 [15] follows. [15].
iris-uri = scheme ":" registry-urn "/"
[ resolution-method ] "/" authority
[ "/" entity-class "/" entity-name ]
scheme = "iris"
authority = // as specified by RFC2396
registry-urn = // as specified by IRIS
resolution-method = *(unreserved | escaped)
entity-class = *(unreserved | escaped)
Newton & Sanz Standards Track [Page 37]
RFC 3981 IRIS-Core December 2004
entity-name = *(unreserved | escaped)
unreserved = // as specified by RFC2396
escaped = // as specified by RFC2396
An IRIS URI MUST NOT be a relative URI. The resolution method,
entity class class, and entity name MUST be of the UTF-8 [12] character set
encoded with "application/x-www-form-urlencoded" "application/x-www-form-urlencoded", as specified by
URL_ENC [14].
When the entity-class and entity-name components are not specified,
the defaults "iris" and "id" MUST be implied. For example,
"iris:dreg1//com" is to be interpreted as "iris:dreg1//com/iris/id".
When the resolution-method is not specified, the default is the
direct resolution method described in Section 7.3.2.
7.2
7.2. Transport Specific Schemes
The "iris" scheme name is not application transport specific. The
URI resolution process MAY determine the application transport. An
Newton & Sanz Expires January 11, 2005 [Page 42]
Internet-Draft iris-core July 2004
example of such a process is the direct resolution (Section 7.3.2)
process, 7.3.2), which
uses the steps outlined in Section 7.3.3 to determine the application
transport.
A mapping between an application transport and IRIS MAY define a
scheme name signifying its use with the semantics of the IRIS URI.
The rules for determining which application transport to use are: are as
follows:
o If an application transport specific scheme name is present, the
application transport it signifies SHOULD be used if possible.
o If a client has a preferred transport and the resolution process
allows for its use, the client MAY use that application transport.
o Otherwise, the default application transport as specified by
IRIS-BEEP IRIS-
BEEP [1] MUST be used.
7.3
7.3. URI Resolution
7.3.1
7.3.1. Registry Dependent Resolution
Interpretation and resolution of the authority component of an IRIS
URI may be altered with the specification of a resolution-method in
the URI. If no resolution-method component is specified in the URI,
the default is the direct resolution method (see Section 7.3.2).
Newton & Sanz Standards Track [Page 38]
RFC 3981 IRIS-Core December 2004
Alternate resolution methods MAY be specified by registry types. The
identifiers for these methods MUST conform to the ABNF in Section
7.1.
7.3.2
7.3.2. Direct Resolution
In the direct resolution process, the authority component of an IRIS
URI may only contain a domain name, a domain name accompanied by a
port number, an IP address, or an IP address accompanied by a port
number. The authority component of the scheme indicates the server
or set of servers authoritatively responsible for a domain according
to records in DNS (Section 7.3.3) if a domain is specified or specified. If an IP
address is specified, it indicates the specific server to be queried if an IP address is
specified. queried.
The rules for resolution are: are as follows:
o If the authority component is a domain name accompanied by a port
number as specified by RFC 2396, the domain name is converted to
an IP address via an A or AAAA record to the DNS.
o If the authority component is a domain name by itself, the
service/transport location (Section 7.3.3) process is used. If
this process produces no results, then the DNS is queried for the
Newton & Sanz Expires January 11, 2005 [Page 43]
Internet-Draft iris-core July 2004
A or AAAA RRs corresponding to the domain name name, and the port
number used is the well-known port of the transport used according
to Section 7.2.
o If the authority component is an IP address, then the DNS is not
queried, and the IP address is used directly. If the port number
is present, it is used directly; otherwise, the port number used
is the well-known port of the transport used according to Section
7.2.
The use of an IPv6 address in the authority component MUST conform to
RFC 2732 [15].
7.3.3
7.3.3. Transport and Service Location
The direct resolution method (Section 7.3.2) uses the profiled use of
the NAPTR and SRV resource records as defined in S-NAPTR [10] to
determine both the location of a set of servers for a given service
and the set of possible transports that may be used. It is
RECOMMENDED that any resolution method not making explicit use of the
direct resolution process should use S-NAPTR [10] in whatever process
it does define.
S-NAPTR
Newton & Sanz Standards Track [Page 39]
RFC 3981 IRIS-Core December 2004
S-NAPTR [10] requires an application service label. The direct
resolution method (Section 7.3.2) uses the abbreviated form of the
registry URN as the application service label. Other resolution
methods MAY specify other application service labels.
See Appendix A for example sample uses of S-NAPTR.
7.4
7.4. IRIS URI Examples
Here are some examples of IRIS URIs and their meaning:
o iris:dreg1//example.com/domain/example.com
* Finds a server authoritative for "example.com" according to the
rules of direct resolution (Section 7.3.2).
* The server is asked for "example.com" in the "domain" index, or
entity class, of the "dreg1" registry.
o iris:dreg1//example.com
* Finds a server authoritative for "example.com" according to the
rules of direct resolution (Section 7.3.2).
* The server is asked for "id" in the "iris" index, or entity
class, of the "dreg1" registry.
o iris:dreg1//com/domain/example.com
* Finds a server authoritative for "com" according to the rules
of direct-resolution (Section 7.3.2).
* The server is asked for "example.com" in the "domain" index, or
entity class, of the "dreg1" registry.
Newton & Sanz Expires January 11, 2005 [Page 44]
Internet-Draft iris-core July 2004
o iris:dreg1//192.0.2.1:44/domain/example.com
* Following the rules of direct-resolution (Section 7.3.2), the
server at IP address 192.0.2.1 on port 44 is queried by using
BEEP.
* The server is asked for "example.com" in the "domain" index, or
entity class, of the "dreg1" registry.
o iris.lwz:dreg1//192.0.2.1:44/domain/example.com
* Following the rules of direct-resolution (Section 7.3.2), the
server at IP address 192.0.2.1 on port 44 is queried by using a
lightweight application transport.
* The server is asked for "example.com" in the "domain" index, or
entity class, of the "dreg1" registry.
Newton & Sanz Standards Track [Page 40]
RFC 3981 IRIS-Core December 2004
o iris.beep:dreg1//com/domain/example.com
* Finds a server authoritative for "com" according to the rules
of direct-resolution (Section 7.3.2).
* Uses the BEEP application transport.
* The server is asked for "example.com" in the "domain" index, or
entity class, of the "dreg1" registry.
o iris:dreg1/bottom/example.com/domain/example.com
* Finds a server authoritative for "example.com" according to the
rules of the resolution method 'bottom' as defined by the
registry type urn:ietf:params:xml:ns:dreg1.
* The application transport used is determined by the 'bottom'
resolution method.
* The server is asked for "example.com" in the "domain" index, or
entity class, of the "dreg1" registry.
o iris.beep:dreg1/bottom/example.com/domain/example.com
* Finds a server authoritative for "example.com" according to the
rules of the resolution method 'bottom' as defined by the
registry type urn:ietf:params:xml:ns:dreg1.
* Uses the BEEP application transport.
* The server is asked for "example.com" in the "domain" index, or
entity class, of the "dreg1" registry.
Newton & Sanz Expires January 11, 2005 [Page 45]
Internet-Draft iris-core July 2004
8. Checklists
8.1
8.1. Registry Definition Checklist
Specifications of registry types MUST include the following explicit
definitions:
o Formal XML syntax deriving from the IRIS XML.
o An identifying registry URN.
o Any registry specific resolution methods.
o A registration of the abbreviated registry URN as an application
service label for compliance with S-NAPTR [10]. Note, Note that this is
a different IANA registry than the registry type URN IANA
registry.
o A list of well-known entity classes.
o A statement regarding the case sensitivity of the names in each
entity class.
8.2
Newton & Sanz Standards Track [Page 41]
RFC 3981 IRIS-Core December 2004
8.2. Transport Mapping Checklist
Specifications of transport mappings MUST include the following
explicit definitions:
o A URI scheme name specific to the transport.
o An application protocol label for compliance with S-NAPTR [10].
See Section 7.3.3. Note, Note that although this is a different IANA
registry than the URI scheme name IANA registry, however, it is RECOMMENDED
that they be the same string of characters.
o The set of allowable character set encodings for the exchange of
XML (see Section 9).
o The set of security mechanisms.
Newton & Sanz Expires January 11, 2005 [Page 46]
Internet-Draft iris-core July 2004
9. Internationalization Considerations
IRIS is represented in XML. XML processors are obliged to recognize
both UTF-8 and UTF-16 [12] encodings. XML provides for mechanisms to
identify and use other character encodings by means of the "encoding"
attribute in the <xml> declaration. Absence of this attribute or a
byte order mark (BOM) means indicates a default of UTF-8 [13] encoding.
Thus, for compatibility reasons, reasons and per RFC 2277 [16], use of UTF-8
[13] is RECOMMENDED with IRIS.
The complete list of character set encoding identifiers is maintained
by IANA at [21].
The application-transport layer MUST define a common set of character
set encodings to be understood by both client and server.
Localization of internationalized strings may require additional
information by from the client. Entity definitions SHOULD use the
"language" type defined by XML_SD [4] to aid clients in the
localization process. See Section 4.3.7.3 as for an example.
Newton & Sanz Expires January 11, 2005 Standards Track [Page 47]
Internet-Draft iris-core July 42]
RFC 3981 IRIS-Core December 2004
10. IANA Considerations
This document makes use of uses a proposed XML namespace and schema registry
specified in XML_URN [9]. Accordingly, the following registration
information is provided for the IANA:
o URN/URI:
* urn:ietf:params:xml:ns:iris1
o Contact:
* Andrew Newton <andy@hxr.us>
* Marcos Sanz <sanz@denic.de>
o XML:
* The XML Schema specified in Section 6
Newton & Sanz Expires January 11, 2005 [Page 48]
Internet-Draft iris-core July 2004
11. Security Considerations
The IRIS XML layer provides no authentication or privacy facilities
of its own. It relies on the application-transport layer for all of
these abilities. Application-transports should explicitly define
their security mechanisms (see Section 8.2).
Referral IRIS registry results may contain entity lookups and search
continuations which that result in a client query operation against another
registry service. Clients S