Introduction to the NUM Protocol

Namespace Utility Modules (NUM) is a DNS-based protocol for storing and retrieving structured data on the internet:

• Data can be stored for any domain name or email address, known as a NUM ID
• Data can be stored for any use case, standardised use cases are defined in Modules
• Data is stored in DNS TXT records, known as NUM Records
• NUM Records are identified using NUM URIs
• NUM URIs are resolved using DNS queries, known as NUM Lookups
• NUM Lookups for custom records (those not based on a module) query the Independent NUM zone only
• NUM Lookups for standardised records query both the Independent NUM Zone and the Hosted NUM zone
• NUM Records can be managed using a simple web interface, known as NUM Server
• An end user consumes NUM Records using a NUM Client

This introduction briefly explains each of the points above, for more detailed information please see the specification .

NUM IDs

NUM uses unique identifiers to store and retrieve data. Domain names and email addresses are valid NUM IDs. World Wide Web addresses are not valid NUM IDs but can be resolved as NUM URIs by using num:// instead of http:// or https://.

Modules

NUM can be used to store NUM Record data of any structure and for any purpose. Use cases can be standardised through modules, each module is numbered. For example, the Contacts module (module 1) is an attempt to standardise how an organisation or individual can associate contact data with their domain name or email address. Anyone can create a module.

NUM Records

NUM Records are DNS TXT records written in CompactData – a character-efficient plain text data serialisation format that's well suited to the DNS. Here's an example NUM Record using the Contacts module:

NUM URIs

NUM records are identified with NUM URIs. NUM records can be structured in a similar way to webpages on the World Wide Web and retrieved using the same URI path concept. NUM URIs take the following structure:

For example:

NUM allows email addresses to be resolved and also contain a path: num://jane.smith@numexample.com:1/path.

When no module is specified 0 is assumed. When no path is specified / is assumed. A module is often specified by a NUM client.

NUM Lookups

NUM Lookups are performed by NUM client libraries.

Using the example NUM ID numexample.com, a NUM Lookup may make DNS queries to two parts of the DNS:

1. The authoritative name server for the domain _num.numexample.com, this is known as the Independent NUM Zone.
2. The NUM Server at _numexample.com.c.7.m.num.net, this is known as the Hosted NUM Zone.

Only the independent NUM zone is queried for custom records (those not based on a module). For records based on a module, the hosted NUM zone is also queried if no record is returned from the independent NUM zone query.

In both cases, DNS queries take the form:

A NUM lookup for num://numexample.com:1/sales results in two DNS queries, the first is to the independent NUM zone:

nslookup -type=TXT sales.1._num.numexample.com

Windows command to retrieve a Contacts record.

dig sales.1._num.numexample.com TXT

Unix command to retrieve a Contacts record.

The second DNS query is to the hosted NUM zone:

nslookup -type=TXT sales.1._numexample.com.c.7.m.num.net

Windows command to retrieve a Contacts record.

dig sales.1._numexample.com.c.7.m.num.net TXT

Unix command to retrieve a Contacts record.

The NUM zone for email address queries is slightly different. Records for email addresses are stored under the label e within the NUM zone. Records for each mailbox (e.g. jane.smith) are stored at a level below that and are underscore prefixed.

For example, a NUM Lookup for the URL num://jane.smith@numexample.com:1 would result in this DNS query to the independent NUM zone:

nslookup -type=TXT 1._jane.smith.e._num.numexample.com

Windows command to retrieve a Contacts record for jane.smith@numexample.com from the independent NUM zone.

dig 1._jane.smith.e._num.numexample.com TXT

Unix command to retrieve a Contacts record for jane.smith@numexample.com from the independent NUM zone..

And this query to the hosted NUM zone:

nslookup -type=TXT 1._jane.smith.e._numexample.com.c.7.m.num.net

Windows command to retrieve a Contacts record from the hosted NUM zone.

dig 1._jane.smith.e._numexample.com.c.7.m.num.net TXT

Unix command to retrieve a Contacts record from the hosted NUM zone.

Independent NUM Zone

NUM Records can be published to the Independent NUM zone for numexample.com by anyone with control over the authoritative nameserver. NUM records can be setup using tools provided by most domain name registrars and all specialist DNS hosting providers.

Hosted NUM Zone

All Hosted NUM Zones exist below the domain num.net. A zone distribution technique is used to spread the load of zones on the NUM Server. In the example Hosted NUM Zone given above (_numexample.com.c.7.m.num.net), notice the labels c.7.m are placed between _numexample.com and num.net. These three labels are based on the first three letters of a hash of the domain name being queried. This enables the NUM Server to serve out billions of records on behalf of hundreds of millions of domain names.

The Hosted NUM Zone is important to help overcome the classic chicken-and-egg problem – where no one stores data using NUM because no one's looking for it, and no one's looking for it because it's not there. The Hosted NUM Zone is populated in two ways:

• Through the NUM Server interface
  After creating an account and proving control over a NUM ID, an individual or organisation can publish structured data to the Hosted NUM Zone using the NUM Server.
• Automatically using public data
  Some records in the Hosted NUM Zone are populated using public data. For example, Contacts records for domain names are populated based on contact data shown on the public website served for that domain name.

NUM Server

The NUM Server offers a service to claim a NUM ID and publish records to the DNS free of charge. To make management of the independent NUM zone easier, it's possible to delegate an independent NUM zone to the NUM Server.

NUM Clients

NUM Clients use NUM Libraries to perform NUM Lookups. Often these clients set the NUM module. For example, in a dialler client the module would be set to 1 for the Contacts module. This means that users could simply query domain names or email addresses, without specifying a module.

Deeper Dive

To get deep into the technical detail read the protocol specification .