IRIS: The Internet Registry Information Service (IRIS) Core Protocol
updated by
- rfc-4992 — XML Pipelining with Chunks for the Internet Registry Information Service
Extracted elements (33)
Entity classes (e.g., 'name-server' vs. 'network') are used to avoid collisions with entity names within a registry type and to allow server implementations to narrow search or lookup scopes quickly to a single index, since the same name (e.g., '192.0.2.0') may refer to different entities in different classes.
Registry types derive element types from the base IRIS schema using XML Schema derivation rather than defining a single monolithic schema. This allows the IRIS framework to be extended for diverse registry needs (domain, address, etc.) without re-versioning the core protocol.
The <answer> and <additional> sections in <resultSet> are separated to allow easier client processing: <answer> contains direct query results (root nodes in a tree widget), while <additional> contains pre-fetched referral results (leaf nodes), eliminating requeries while preserving the distinction for display purposes.
During deserialization, servers MUST change the authority attribute of a referral to a valid authority of the server if the serialized attribute is empty. During serialization, servers MUST leave the authority attribute empty for referrals where the referent is an entity the server answers queries for.
For compatibility and per RFC 2277, use of UTF-8 is RECOMMENDED with IRIS. The application-transport layer MUST define a common set of character set encodings understood by both client and server. Entity definitions SHOULD use the 'language' type to aid client localization.
If an application transport specific URI scheme name is present it SHOULD be used if possible. Otherwise, the default application transport specified by IRIS-BEEP MUST be used. Clients MAY use a preferred transport if the resolution process allows it.
If <onlyCheckPermissions> is rejected, the server MUST return all appropriate result sets but all result sets MUST be empty of results and MUST contain no errors. This control applies to all search sets or none; a server MUST issue a rejection if it cannot be accepted for all search sets.
IRIS defines two default entity classes 'local' and 'iris' which MUST NOT be redefined and MUST be valid in all registry types. The 'iris' class MUST contain entity names 'id' (yielding <serviceIdentification>) and 'limits' (yielding <limits>).
Registry schemas MUST derive elements to define typed queries and results from the base IRIS schema. The identifier for a registry type and its XML namespace identifier MUST be the same URN registered in the 'ns' class of the IANA registry governed by XML_URN.
Registry type specifications MUST include: formal XML syntax deriving from IRIS XML, an identifying registry URN, any registry-specific resolution methods, a registration of the abbreviated URN as an S-NAPTR application service label, a list of well-known entity classes, and a statement on case sensitivity of entity names.
Registry type URN identifiers MUST be restricted to a URN registered in the 'ns' class of the IANA registry and are case insensitive. These identifiers MAY be abbreviated to the part following the class component, but this abbreviation MUST NOT be used inside XML instances.
Servers MUST return direct answers to queries in the <answer> element and MAY return results in the <additional> element for which a reference has been made in the <answer>. Results in <additional> MUST have been referenced in the <answer>.
The client MUST NOT make any assumptions about the contents of a bag when relaying it. A server MUST NOT ignore a bag when received; if a bag cannot be recognized or accepted, one of the bag error codes MUST be returned.
The direct resolution method uses S-NAPTR (profiled NAPTR and SRV records) to determine server location and available transports. It is RECOMMENDED that any resolution method not using direct resolution should use S-NAPTR in whatever process it defines. The abbreviated registry URN is used as the S-NAPTR application service label.
The root element of all request XML instances MUST be <request> and the root element of all response XML instances MUST be <response>. These elements and their closing tags MUST be applied to all requests and responses sent by both clients and servers.
Transport mapping specifications MUST include: a URI scheme name, an S-NAPTR application protocol label, the set of allowable character set encodings for XML exchange, and the set of security mechanisms.
Versioning of the IRIS protocol is the responsibility of the application-transport layer but MUST be associated with the XML namespace URI representing IRIS. A change in this URI indicates a new version of the protocol.
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 referral loop.
When the 'temporaryReference' attribute is true, the entity reference data is only valid within the response in which it appears. A server MUST include the referent of any temporary entity reference in the <additional> section of the same <resultSet>.
A <request> element contains an optional <control> element and one or more <searchSet> elements. Each <searchSet> contains either a <lookupEntity> element (with attributes 'registryType', 'entityClass', 'entityName') or a derived <query> element, plus an optional <bag> child.
A <response> element contains an optional <reaction> element, one or more <resultSet> elements, and an optional <bags> element. Each <resultSet> contains an <answer> element, an optional <additional> element, and error elements if applicable.
Error elements defined in <resultSet> include: <insufficientResources>, <invalidName>, <invalidSearch>, <queryNotSupported>, <limitExceeded>, <nameNotFound>, <permissionDenied>, <bagUnrecognized>, <bagUnacceptable>, <bagRefused>, and derivatives of <genericCode>.
IRIS has three framework layers: Registry-Specific (defines queries, results, entity classes per registry type), Common-Registry (base operations, search sets, referrals), and Application-Transport (authentication, message passing, session management, URI syntax). Each registry type is identified by a URN.
Relay bags allow a server to relay opaque information to a referent server via the client. Bags are generated by the queried server, passed as opaque data to the client, and included in subsequent requests to referent servers via the 'bagRef' (IDREF) attribute on entity references and search continuations.
The IRIS URI has the general syntax: iris:<registry>/<resolution>/<authority>/<class>/<name>. All components use UTF-8 encoded with 'application/x-www-form-urlencoded'. An IRIS URI MUST NOT be a relative URI. When entity-class and entity-name are absent, defaults 'iris' and 'id' are implied.
The <limits> result element (accessed via entityClass='iris', entityName='limits') informs clients of service limits, with optional <totalQueries>, <totalResults>, <totalSessions>, and <otherRestrictions> children, each with per-second/minute/hour/day sub-elements.
The <onlyCheckPermissions> control asks the server only to check whether adequate permissions are available to execute queries. The server MUST respond with a <standardReaction> element containing one of: <controlAccepted>, <controlDenied>, <controlDisabled>, or <controlUnrecognized>.
The <serialization> element enables serialization of IRIS registry entities to file storage. It contains <result> derivatives (entities) and <serializedReferral> elements. Servers loading entities MUST place them in entity classes specified by 'registryType', 'entityClass', and 'entityName' attributes.
The <serviceIdentification> result element (accessed via entityClass='iris', entityName='id') provides clients with service instance identification, containing <authorities>, optional <operatorName>, <eMail>, <phone>, and <seeAlso> elements.
The <simpleEntity> result element allows service operators to make simple name-value pair additions without defining new registry types. Its <property> children carry 'name', 'language', and optional 'uri' attributes.
This document registers the XML namespace 'urn:ietf:params:xml:ns:iris1' and the associated XML Schema (Section 6) in the IANA IETF XML registry governed by RFC 3688.
Clients SHOULD NOT use authentication credentials and mechanisms subject to replay attacks when conducting entity lookups and search continuations that result from referrals in IRIS registry results, since referrals may direct queries to different registry services.
The IRIS XML layer provides no authentication or privacy facilities of its own; it relies entirely on the application-transport layer for these capabilities. Application-transports must explicitly define their security mechanisms as required by the transport mapping checklist.