Why whois needed replacing
whois is older than the web. It was designed when the number of registered names was small enough
to print, and it has no schema: a server returns lines of text in whatever layout it prefers, with
whatever labels it prefers, and the client is expected to work it out. Two registries can express
the same fact as Updated Date, changed, last-modified or
nothing at all. Every tool that reads whois therefore carries a pile of per-registry parsing rules,
and every one of those rules is a place where a wrong answer can be produced silently.
RDAP fixes the format rather than the content. It returns the same facts as a whois record, as JSON, over HTTPS, with member names defined in a specification rather than by convention. It has proper status codes, so a name that does not exist produces a 404 instead of a paragraph of prose that has to be pattern-matched. And it has a defined place to say "this was withheld", which whois never had.
The shape of a response
A domain response is one JSON object. The members that matter are few, and once they are familiar the rest is noise.
Top-level members
| Member | What it holds |
|---|---|
| objectClassName | Always domain for a domain query. Confirms you are reading what you think you are. |
| handle | The registry's identifier for this registration. Changes when the registration does, which makes it a quiet confirmation of a drop. |
| ldhName | The name in letters-digits-hyphen form. An internationalised name also carries unicodeName. |
| status | An array of status strings: the RDAP spelling of the EPP codes, lower-cased and space-separated. |
| events | The dated history: registration, last changed, expiration, and the timestamp of the database itself. |
| nameservers | An array of objects, each with its own ldhName. Absent entirely when nothing is delegated. |
| entities | The parties: registrar, and where published, registrant and technical contacts, each with a roles array. |
| secureDNS | Whether the delegation is signed, and the delegation-signer records if it is. |
| notices / remarks | Legal text, terms of use, and, importantly, redaction statements. |
Note what is missing from that list: there is no field for traffic, age in any human sense, ownership history, or anything about the site. RDAP is the registry's view, and the registry only ever knew about the registration. The rest of what can be known about a website comes from elsewhere and is weaker.
The events array
This is the part worth reading first, and the part most tools flatten badly. Each event is a pair:
an eventAction naming what happened, and an eventDate in RFC 3339 form.
Four actions cover almost everything.
Event actions
| eventAction | What it means |
|---|---|
| registration | When the current registration was created. Not when the name first existed anywhere.A recent registration date on a name with a long external history is the signature of a domain that lapsed and was re-registered by someone new. |
| last changed | The most recent material modification.Moves on transfer, nameserver change, status change and renewal. The single most informative value in the whole response. |
| expiration | The end of the paid term.Not the date the name is released. See the domain lifecycle for the windows that follow. |
| last update of RDAP database | When this response was generated.Freshness of the answer, not of the registration. Easy to mistake for one of the others. |
Read together, registration and last changed reconstruct a history that no other free source provides. A registration date of 2009 with a last changed date of last week describes a long-established name that has just been touched. A registration date of last month on a name that third-party sources have been citing since 2012 describes a name that fell out of registration and came back under new control. Neither conclusion needs any paid tool.
Entities, roles and redaction
Parties appear as objects in the entities array, each carrying a roles
array. The role vocabulary is small: registrar, registrant,
administrative, technical, abuse. The registrar entity is
essentially always present and usually carries a publicIds member holding the IANA
identifier, which is the stable way to name a registrar across rebrands.
Contact detail inside an entity is expressed as a jCard: a JSON serialisation of the vCard format, which is why the structure looks strangely nested for what is only a name and an address. In practice most of it is absent. Where a field has been withheld, a well-behaved server says so in a redaction notice rather than silently omitting it, and that explicit statement is one of the real improvements over whois, where a missing line and a withheld line looked identical.
Status and notices
RDAP status values are the EPP codes in a different spelling: client transfer
prohibited rather than clientTransferProhibited. The meanings are unchanged and
are laid out completely on the whois record page. The
important habit is to read the array rather than the first element, because the codes combine and
the combination is the state. A name that is both client transfer prohibited and
server hold is locked and not resolving at the same time.
Notices and remarks are where registries put terms of use, rate-limit statements and redaction explanations. They are easy to skip and occasionally load-bearing: a rate-limit notice is the reason a script that worked yesterday returns nothing today.
Reading a response quickly
Four values answer most questions. Take events and find registration and last
changed. Take status and read the whole array. Take nameservers and note
whether it is present at all: its absence is the
undelegated state, where a name is registered
and resolves to nothing. Take the registrar entity's IANA identifier if you need to name the
sponsor precisely. Everything else can wait.
If you have a response in front of you, the record field decoder accepts RDAP JSON as well as whois text and labels every member it recognises, entirely in the browser. It is the fastest way to see which of the fields you expected are simply not there.
