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 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 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 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:

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

For example:

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

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:

[<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..