3. Relation Searches
This section preserves the RFC text for RDAP RIR search, including rirSearch1, ips, autnums, ipSearchResults, autnumSearchResults, relation links, JSON examples, response behavior, reverse search, conformance, and IANA registrations.
Original RFC Text
3. Relation Searches
This section defines searches and link relations for finding objects
and sets of objects with respect to their position within a
hierarchy.
3.1. Path Segments
The variables used in the path segments in this section include:
<relation>: a relation type, as defined in Section 3.2.2 of this
document.
<IP address>: an IP address, as defined in Section 3.1.1 of
[RFC9082].
<CIDR prefix>: the first address of a Classless Inter-Domain Routing
(CIDR) block, as defined in Section 3.1.1 of [RFC9082].
<CIDR length>: the prefix length for a CIDR block, as defined in
Section 3.1.1 of [RFC9082].
<domain name>: a fully qualified domain name, as defined in
Section 3.1.3 of [RFC9082].
<autonomous system number or range>: an autonomous system number, as
defined in Section 3.1.2 of [RFC9082], or two such numbers
separated by a single hyphen ('-', ASCII value 0x2D), where the
second number is greater than the first.
<resource type search path segment>: a search path segment
corresponding to an Internet Number Resource (INR) object class
(i.e., an IP network address or range, autonomous system number or
number range, or reverse domain name).
<object value>: a value used to identify an object for the purposes
of a relation search relative to that object. One of <IP
address>, <CIDR prefix> and <CIDR length> pair, <domain name>, or
<autonomous system number or range>, depending on the type of
search that is being performed.
<status>: an object status value, as defined in Section 4.6 of
[RFC9083].
The new resource type path segments for relation search (similar to
the searches defined in [RFC9082] and [RFC9083]) are:
'ips/rirSearch1/<relation>/<IP address>': Used to identify an IP
network search using a relation and an IP address to match a set
of IP networks.
'ips/rirSearch1/<relation>/<CIDR prefix>/<CIDR length>': Used to
identify an IP network search using a relation and an IP address
range to match a set of IP networks.
'autnums/rirSearch1/<relation>/<autonomous system number or
range>': Used to identify an autonomous system number search using a
relation and a single ASN or an ASN range to match a set of ASN
objects.
'domains/rirSearch1/<relation>/<domain name>': Used to identify a
reverse domain search using a relation and a reverse domain name
to match a set of reverse domains.
3.2. Relation Search
Syntax: <resource type search path
segment>/rirSearch1/<relation>/<object value>[?status=<status>]
The relation searches defined in this document rely on the syntax
described above. Each search works in the same way for each object
class.
The rirSearch1 path segment is used in the relation search URLs in
order to provide a single namespace for those searches, and so that
other searches can be defined underneath the top-level resource type
search path segments.
3.2.1. Definitions
An INR object value may have a "parent" object and one or more
"child" objects. The "parent" object is the next-least-specific
object that exists in the relevant registry, while the "child"
objects are the next-most-specific objects that exist in the relevant
registry. For example, let's say there is a registry with the
following IP network objects:
+--------------+
| 192.0.2.0/24 |
+--------------+
/ \
+--------------+ +----------------+
| 192.0.2.0/25 | | 192.0.2.128/25 |
+--------------+ +----------------+
/ / \
+--------------+ +----------------+ +----------------+
| 192.0.2.0/28 | | 192.0.2.128/26 | | 192.0.2.192/26 |
+--------------+ +----------------+ +----------------+
/
+--------------+
| 192.0.2.0/32 |
+--------------+
Figure 1: Example Registry Objects
For this example registry, the INR object value to parent/child
object relationships are:
+==================+================+
| INR object value | Parent object |
+==================+================+
| 192.0.2.0/32 | 192.0.2.0/28 |
+------------------+----------------+
| 192.0.2.0/28 | 192.0.2.0/25 |
+------------------+----------------+
| 192.0.2.64/26 | 192.0.2.0/25 |
+------------------+----------------+
| 192.0.2.128/26 | 192.0.2.128/25 |
+------------------+----------------+
| 192.0.2.192/26 | 192.0.2.128/25 |
+------------------+----------------+
| 192.0.2.0/25 | 192.0.2.0/24 |
+------------------+----------------+
| 192.0.2.128/25 | 192.0.2.0/24 |
+------------------+----------------+
| 192.0.2.0/24 | N/A |
+------------------+----------------+
Table 1: Parent Objects
+==================+================================+
| INR object value | Child objects |
+==================+================================+
| 192.0.2.0/24 | 192.0.2.0/25, 192.0.2.128/25 |
+------------------+--------------------------------+
| 192.0.2.0/25 | 192.0.2.0/28 |
+------------------+--------------------------------+
| 192.0.2.128/25 | 192.0.2.128/26, 192.0.2.192/26 |
+------------------+--------------------------------+
| 192.0.2.64/26 | N/A |
+------------------+--------------------------------+
| 192.0.2.128/26 | N/A |
+------------------+--------------------------------+
| 192.0.2.192/26 | N/A |
+------------------+--------------------------------+
| 192.0.2.0/28 | 192.0.2.0/32 |
+------------------+--------------------------------+
| 192.0.2.0/32 | N/A |
+------------------+--------------------------------+
Table 2: Child Objects
(INR object values do not necessarily correspond to registry objects,
because users can provide arbitrary object values as input to the
searches defined in this document.)
Similarly to the parent/child object relationships, each INR object
value may have a "top" object, being the least-specific covering
object that exists in the registry, and one or more "bottom" objects,
being the most-specific objects that entirely cover the INR object
value when taken together. Given the registry defined above, the top
and bottom object relationships are:
+==================+==============+
| INR object value | Top object |
+==================+==============+
| 192.0.2.0/32 | 192.0.2.0/24 |
+------------------+--------------+
| 192.0.2.0/28 | 192.0.2.0/24 |
+------------------+--------------+
| 192.0.2.64/26 | 192.0.2.0/24 |
+------------------+--------------+
| 192.0.2.128/26 | 192.0.2.0/24 |
+------------------+--------------+
| 192.0.2.192/26 | 192.0.2.0/24 |
+------------------+--------------+
| 192.0.2.0/25 | 192.0.2.0/24 |
+------------------+--------------+
| 192.0.2.128/25 | 192.0.2.0/24 |
+------------------+--------------+
| 192.0.2.0/24 | N/A |
+------------------+--------------+
Table 3: Top Objects
+==================+===========================================+
| INR object value | Bottom objects |
+==================+===========================================+
| 192.0.2.0/24 | 192.0.2.0/25, 192.0.2.0/28, 192.0.2.0/32, |
| | 192.0.2.128/26, 192.0.2.192/26 |
+------------------+-------------------------------------------+
| 192.0.2.0/25 | 192.0.2.0/25, 192.0.2.0/28, 192.0.2.0/32 |
+------------------+-------------------------------------------+
| 192.0.2.128/25 | 192.0.2.128/26, 192.0.2.192/26 |
+------------------+-------------------------------------------+
| 192.0.2.64/26 | N/A |
+------------------+-------------------------------------------+
| 192.0.2.128/26 | N/A |
+------------------+-------------------------------------------+
| 192.0.2.192/26 | N/A |
+------------------+-------------------------------------------+
| 192.0.2.0/28 | 192.0.2.0/28, 192.0.2.0/32 |
+------------------+-------------------------------------------+
| 192.0.2.0/31 | 192.0.2.0/28, 192.0.2.0/32 |
+------------------+-------------------------------------------+
| 192.0.2.0/32 | N/A |
+------------------+-------------------------------------------+
Table 4: Bottom Objects
If there are no more-specific objects for a given INR object value,
then the set of bottom objects for that INR object value will be
empty. 192.0.2.0/32 is an example of such an INR object value.
It is not necessarily the case that the bottom objects for a given
INR object value will be disjoint. For example, 192.0.2.0/28's
bottom objects are 192.0.2.0/28 and 192.0.2.0/32. 192.0.2.0/32 is
included because it is one of the most-specific objects (i.e., an
object at the bottom of the object hierarchy) for 192.0.2.0/28, while
192.0.2.0/28 itself is included because it is the most-specific
object for the other addresses within the range (i.e., those aside
from 192.0.2.0/32).
The bottom objects for a given INR object value may include an object
that is less specific than that INR object value. For example,
192.0.2.0/31 is an INR object value that has a more-specific object,
being 192.0.2.0/32, so the set of bottom objects must include at
least that object. The most-specific object that covers the residual
(i.e., 192.0.2.1/32) is 192.0.2.0/28, so it is included in the
results as well.
3.2.2. Relations
3.2.2.1. Single-Result Searches
3.2.2.1.1. "rdap-up"
If the server receives a search containing the relation value "rdap-
up", it will return the parent object for the specified INR object
value as though that object had been requested directly. If no such
object exists, it will respond with an HTTP 404 (Not Found) [RFC9110]
status code.
3.2.2.1.2. "rdap-top"
If the server receives a search containing the relation value "rdap-
top", it will return the top object for the specified INR object
value as though that object had been requested directly. If no such
object exists, it will respond with an HTTP 404 (Not Found) [RFC9110]
status code.
3.2.2.2. Multiple-Result Searches
3.2.2.2.1. "rdap-down"
If the server receives a search containing the relation value "rdap-
down", it will return the child objects for the specified INR object
value. If no such objects exist, it will return an empty search
response. Per the definitions section, this includes only immediate
child objects.
3.2.2.2.2. "rdap-bottom"
If the server receives a search containing the relation value "rdap-
bottom", it will return the bottom objects for the specified INR
object value. If no such objects exist, it will return an empty
search response.
3.3. Status
If the "status" argument is provided, then response processing will
proceed as though all objects without the specified status had first
been removed from the database. For example, if the registry objects
from Section 3.2.1 had the following statuses:
+================+==========+
| Object | Status |
+================+==========+
| 192.0.2.0/25 | active |
+----------------+----------+
| 192.0.2.128/25 | inactive |
+----------------+----------+
| 192.0.2.128/26 | active |
+----------------+----------+
| 192.0.2.192/26 | active |
+----------------+----------+
Table 5: Statuses
then a server receiving a "rdap-down" search request with the INR
object value 192.0.2.0/24 and a "status" argument of "active" would
return the objects 192.0.2.0/25, 192.0.2.128/26, and 192.0.2.192/26.
Status filtering is useful, for example, where the client is trying
to find the delegation from an RIR to an RIR account holder: by using
the "rdap-top" relation with a "status" of "active", the delegation
from IANA to the RIR will be ignored, and the client will receive the
delegation from the RIR to the account holder in the response
instead.
By default, any valid status value may be used for status filtering.
Server operators MAY opt not to support "status" filtering for the
"rdap-down" and "rdap-bottom" link relations, in which case the
server responds with an HTTP 501 (Not Implemented) [RFC9110] response
code if it receives such a request. Server operators MAY also opt
not to support "status" filtering for values other than "active" for
the "rdap-up" and "rdap-top" link relations, in which case the server
responds with an HTTP 501 (Not Implemented) [RFC9110] response code
if it receives such a request.
While any valid status value may be used for status filtering, a
given RDAP server may make use of only a small number of those status
values for INR objects. For example, a status value like "client
hold" would typically only be used by a DNR for a forward domain name
object.
3.4. Link Relations
Each of the relations defined in Section 3.2.2 has a corresponding
link relation that can be used for a link object contained within
another RDAP object. When constructing these link objects, the
server MUST use the corresponding search URL for the link target, or
a URL that yields the same response as for the corresponding search
as at the time of the request. The following is an elided example of
an IPv4 response that makes use of those link relations:
{
"startAddress": "192.0.2.0",
"endAddress": "192.0.2.127",
...
"links": [
...,
{
"value": "https://example.com/rdap/ip/192.0.2.0/25",
"rel": "rdap-up",
"href": ".../rdap/ips/rirSearch1/rdap-up/192.0.2.0/25",
"type": "application/rdap+json"
},
{
"value": "https://example.com/rdap/ip/192.0.2.0/25",
"rel": "rdap-down",
"href": ".../rdap/ips/rirSearch1/rdap-down/192.0.2.0/25",
"type": "application/rdap+json"
},
{
"value": "https://example.com/rdap/ip/192.0.2.0/25",
"rel": "rdap-top",
"href": ".../rdap/ips/rirSearch1/rdap-top/192.0.2.0/25",
"type": "application/rdap+json"
},
{
"value": "https://example.com/rdap/ip/192.0.2.0/25",
"rel": "rdap-bottom",
"href": ".../rdap/ips/rirSearch1/rdap-bottom/192.0.2.0/25",
"type": "application/rdap+json"
}
]
}
Figure 2: Example Links in an IPv4 Response
The following is an elided example of an IPv6 response that makes use
of the link relations:
{
"startAddress": "2001:db8:a::",
"endAddress": "2001:db8:a:ffff:ffff:ffff:ffff:ffff",
...
"links": [
...,
{
"value": "https://example.com/rdap/ip/2001:db8:a::/48",
"rel": "rdap-up",
"href": ".../rdap/ips/rirSearch1/rdap-up/2001:db8:a::/48",
"type": "application/rdap+json"
},
{
"value": "https://example.com/rdap/ip/2001:db8:a::/48",
"rel": "rdap-down",
"href": ".../rdap/ips/rirSearch1/rdap-down/2001:db8:a::/48",
"type": "application/rdap+json"
},
{
"value": "https://example.com/rdap/ip/2001:db8:a::/48",
"rel": "rdap-top",
"href": ".../rdap/ips/rirSearch1/rdap-top/2001:db8:a::/48",
"type": "application/rdap+json"
},
{
"value": "https://example.com/rdap/ip/2001:db8:a::/48",
"rel": "rdap-bottom",
"href": ".../rdap/ips/rirSearch1/rdap-bottom/2001:db8:a::/48",
"type": "application/rdap+json"
}
]
}
Figure 3: Example Links in an IPv6 Response
One additional link relation, "rdap-active", is defined for denoting
a search with a "status" of "active". No other status link relations
are defined because the only known use cases for status filtering
involve the "rdap-up" and "rdap-top" relations and the "active"
status. The following is an elided example of an IPv4 response that
makes use of those link relations:
{
"startAddress": "192.0.2.0",
"endAddress": "192.0.2.127",
...
"links": [
...,
{
"value": "https://example.com/rdap/ip/192.0.2.0/25",
"rel": "rdap-up rdap-active",
"href":
".../rdap/ips/rirSearch1/rdap-up/192.0.2.0/25?status=active",
"type": "application/rdap+json"
},
{
"value": "https://example.com/rdap/ip/192.0.2.0/25",
"rel": "rdap-top rdap-active",
"href":
".../rdap/ips/rirSearch1/rdap-top/192.0.2.0/25?status=active",
"type": "application/rdap+json"
}
]
}
Figure 4: Example Status Links in an IPv4 Response
The following is an elided example of an IPv6 response that makes use
of the link relations:
{
"startAddress": "2001:db8:a::",
"endAddress": "2001:db8:a:ffff:ffff:ffff:ffff:ffff",
...
"links": [
...,
{
"value": "https://example.com/rdap/ip/2001:db8:a::/48",
"rel": "rdap-up rdap-active",
"href":
".../rdap/ips/rirSearch1/rdap-up/2001:db8:a::/48?status=active",
"type": "application/rdap+json"
},
{
"value": "https://example.com/rdap/ip/2001:db8:a::/48",
"rel": "rdap-top rdap-active",
"href":
".../rdap/ips/rirSearch1/rdap-top/2001:db8:a::/48?status=active",
"type": "application/rdap+json"
}
]
}
Figure 5: Example Status Links in an IPv6 Response
"rdap-active" is used only as a link relation in a link object. It
cannot be used as a value for <relation> in the relation search URL
defined in Section 3.2. Section 3.3 details status filtering for
relation search URLs.
Since the "rdap-top" and "rdap-up" link relations resolve either to a
single object or to an HTTP 404 (Not Found) [RFC9110] response, it is
possible for a server to use a lookup URL (see Section 3.1 of
[RFC9082]) in the "href" attribute in the link object. The following
is an elided example of an IPv4 response that uses this approach:
{
"startAddress": "192.0.2.0",
"endAddress": "192.0.2.127",
...
"links": [
...,
{
"value": "https://example.com/rdap/ip/192.0.2.0/25",
"rel": "rdap-up",
"href": "https://example.com/rdap/ip/192.0.2.0/24",
"type": "application/rdap+json"
}
]
}
Figure 6: Example Single-Result Links in an IPv4 Response
The following is an elided example of an IPv6 response that makes use
of the approach:
{
"startAddress": "2001:db8:a::",
"endAddress": "2001:db8:a:ffff:ffff:ffff:ffff:ffff",
...
"links": [
...,
{
"value": "https://example.com/rdap/ip/2001:db8:a::/48",
"rel": "rdap-up",
"href": "https://example.com/rdap/ip/2001:db8::/32",
"type": "application/rdap+json"
}
]
}
Figure 7: Example Single-Result Links in an IPv6 Response
Use of these link relations in responses is OPTIONAL. The absence in
a response of a link for a specific relation does not necessarily
mean that the corresponding search will return no results.