Introduction to the NUM Protocol

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

This introduction briefly explains each of the points above, for more detailed information please see the specification Content elsewhere on this site..

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 URLs by using num:// instead of http:// or https://.

Modules

NUM can be used for any kind of structured data. Use cases are standardised through modules and 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. Data can be stored without a module, using module zero.

NUM Records

NUM Records are DNS TXT records written in MODL Content on another site. – 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:

_n=1;o(n=NUM Example Co;s=Example Strapline;c[t=Customer Service:441270123456;fb=examplefacebook;tw=exampletwitter;in=exampleinstagram])
A record showing a telephone number, Facebook page, Twitter and Instagram handle.

A NUM Library unpacks the record using a record configuration file and returns a simple, useful and developer-friendly object:

Loading
An unpacked Contacts record.

NUM URLs

NUM data is located with URLs. NUM records can be structured in a similar way to webpages on the World Wide Web and retrieved using the same URL path concept. NUM URLs take the following structure:

num://<NUM-ID>[:<module>][/<path>]
NUM URL structure.

For example:

num://numexample.com:1/path/to/record
Example NUM URL.

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 to deal with DNS complexities.

Using the example NUM ID numexample.com, a NUM Lookup makes 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.

A record returned from the independent NUM zone always takes precedence.

In both cases, DNS queries take the form:

[<converted-path>.]<module>.<num-zone>
DNS query structure for NUM Lookups.

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

  • Command Prompt
  • Terminal
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:

  • Command Prompt
  • Terminal
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:

  • Command Prompt
  • Terminal
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:

  • Command Prompt
  • Terminal
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:

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 Content elsewhere on this site..