In use with IRIS, this abbreviation MUST NOT be used inside of XML
instances in 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. Entity Classes
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 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", 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/
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):
o "id", which yields a result of <serviceIdentification> (see
Section 4.3.7.1).
o "limits", which yields a result of <limits> (see Section 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,
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.
4.3.4. Names of Entities
The names of entities in a registry schema are of type 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 (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 as having different case
sensitivity.
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 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
name of the new element 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 clients
with a more 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 attributes specify where
the entity may be found.
o ’temporaryReference’ -- This attribute is optional. See Section
4.3.6.
o ’referentType’ -- 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
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., ’iris:referentType’). This
allows clients to recognize entity references using an element
derived from <entity>.
o ’bagRef’ -- This attribute is optional. If present, 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. Temporary Entities
Instances may exist in which an entity reference needs to be
temporary. For example, a particular type of result may only have
one unique key. If that key contains semantic meaning that may not
be exposed to all users, a synthetic key will have to be substituted.
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 have to be
temporarily produced.
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 (e.g.,
’entityClass’, ’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. <result> Derived Elements
The base IRIS framework contains three elements directly derived from
the <result> element for use by any registry type.
4.3.7.1. <serviceIdentification>
An example of a <serviceIdentification> result:
<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>
Internet Assigned Numbers Authority
</operatorName>
<eMail>
iana@iana.org
</eMail>
</serviceIdentification>
The <serviceIdentification> element is provided to allow IRIS clients
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. Although a server MAY
only return a partial list of its authority areas, depending on
operator policy, it MUST return the authority for which the client
has requested.
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. <limits>
An example of a <limits> result:
<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 allowing a server to inform
a client of the limits it may encounter from 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 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.
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
that it has no limits by using a <limits> element with no content
(e.g., <limits authority=... />).
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 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 and an optional URI pointing to more information.
Clients may easily display such information in a two-column table.
Applications using binary data or richer data structures are out of
scope for this element. When such usage scenarios arise, a client
will likely need specific knowledge to handle such data, thus calling
the need for a new registry 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>, and its
requisite reaction, <standardReaction>, for compliance with CRISP
[17].
When a client sends an <onlyCheckPermissions> control, it is only
asking the server to check to see whether adequate permissions are
available to execute the queries in the associated request. A server
MUST respond to this control with a <standardReaction> element.
The <standardReaction> element provides a server with a standard
means to respond to controls (it may be used by other controls, but
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., 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 of them; therefore a server MUST issue a
rejection if <onlyCheckPermissions> cannot be accepted for all search
sets in a request.
An example of an IRIS XML exchange using these 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 />
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. Relay Bags
IRIS employs 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 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
specify a bag only once but allows each entity reference or search
continuation (in all result sets) to have a distinct 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
it is received. In case 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 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" />
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:
S: <bag id="x1">
S: <simpleBag xmlns="http://example.com/">
S: AAAAB3NzaC1yc2EAAAABIwAAAIEA0ddD+W3Agl0Lel98G1r77fZ
S: </simpleBag>
S: </bag>
S:
S: </bags>
S: </response>
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. This section will use terms defined
by RFC 2119 [8] to describe these. While reading this section,
please reference Section 6 for needed details on the formal XML
syntax.
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 and
<serializedReferral> elements.
Derivatives of the <result> element are entities. Servers loading
these entities MUST place the entity in the entity classes specified
by the elements ’registryType’, ’entityClass’, and ’entityName’
attributes and in any entity classes the entities may apply according
to explicitly defined children of that element. For instance, if a
registry type has two entity classes "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
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 containing the ’authority’, ’resolution’ (optional),
’registryType’, ’entityClass’, and ’entityName’ attributes. The
attributes of this element are used to signify the entity 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
entity for which the server answers queries.
The following is an example of serialized 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">
<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"
entityName="notice" >
<property name="legal" language="en">
Please use the net wisely!
</property>
</simpleEntity>
</iris:serialization>
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>