Namespace Utility Modules (NUM) Specification

"

Introduction

Millions of organisations and individuals have used their public facing website to publish useful data about themselves – e.g. contact information, logos, registration numbers and more. However, data presented on the web in this way is often not structured or easily machine readable. Web standards for structuring this data have a high technical barrier for adoption and can be inefficient when they require full HTML documents to be downloaded and parsed.

Many service providers collect structured and unstructured data from the web for indexing and inclusion in social graphs and knowledge graphs. However, the data isn't made freely available and each provider requires the data subject to use a different method to manage and update it.

The Namespace Utility Modules (NUM) protocol provides a way to store structured data in, and retrieve structured data from, the DNS. Data can be stored for any domain name or email address. Data is stored in DNS TXT records known as NUM records. Records are located using a NUM URI which is resolved using a series of DNS queries known as a NUM lookup.

Use cases for NUM records are standardised with modules. A NUM lookup for a custom record makes a query to the authoritative nameserver only. A lookup for a standardised record (a record based on a module) first queries the authoritative nameserver and if no record is returned, a query is then made to the NUM Server – a DNS-based store of NUM records that organisations and individuals can use to adopt the NUM protocol through a simple, user-friendly web interface.

Status

The NUM protocol specification is currently a draft, we are inviting members of the technical community to provide feedback – to do that please contact us Content elsewhere on this site..

Conventions in this Document

The key words "must", "must not", "required", "shall", "shall not", "should", "should not", "recommended", "may", and "optional" are to be interpreted as described in RFC2119 Content on another site..

Audience

This specification is written for readers looking for an in-depth understanding of the NUM protocol – how records are stored in the DNS and how they are retrieved by NUM clients. For a much lighter read, please see the technical introduction Content elsewhere on this site..

Author

NUM was created by Elliott Brown of NUM Technology Ltd.

Example Zone

To help understand how NUM fits into the DNS, we have illustrated an example zone:

Click the thumbnail to expand below or download this PDF Content elsewhere on this site..You can view the example zone in this PDF Content elsewhere on this site..
The zone shows how NUM fits into the DNS for the domain name numexample.com, this domain name is used throughout this specification and many of the examples used in the specification are reflected in this example zone.

NUM ID

NUM uses unique identifiers to store and retrieve data known as NUM IDs. Domains and email addresses are valid NUM IDs. Web addresses are not valid NUM IDs but can be resolved as NUM URIs Content further down this document., using num:// instead of http:// or https://.

NUM Domain

For the purposes of this specification, the domain name in the NUM ID is known as the NUM Domain. For example, the NUM IDs numexample.com and alice@numexample.com both share the same NUM Domain – numexample.com.

NUM Module

Modules can be used to standardise particular use cases – this helps facilitate adoption on both sides: server and client. Modules can also make object description more efficient. Some examples are shown below.

NUM records are not limited to storing particular types of data, any data can be stored using a custom NUM record.

Example Modules

These modules demonstrate some ways that the NUM protocol can be used:

Contacts

Company contact information on the web is fragmented and unstructured. Storing this data in a NUM record makes it fast, efficient and machine-readable. NUM Contacts creates lots of new possibilities, like dialling a company domain name as if it were a telephone number and working through call centre options on your touch screen device before even starting your call.

Registrant

The growth of invalid, incorrect and proxy domain name registrant data has undermined the principles of the WHOIS Content on another site. protocol. More recently, GDPR has all but destroyed it. NUM Registrant records provide a way for registrants, not registrars, to store and serve registrant data – using the DNS.

Custodian

Proving ownership and/or control over a domain name is complex. Many service providers require business owners, website administrators and marketing teams to add records to their DNS to prove authority for a domain name. With NUM Custodian records, a domain administrator can store a list of hashed identifiers (e.g. email addresses) in their DNS once so that all service providers can easily verify who's a custodian for a domain name. This module is currently a proposal.

Creating a Module

Module configuration files are written in MODL Content on another site.. Once the module is published it can be adopted by anyone, either independently in their own DNS or through the user-friendly NUM Server Content on another site. service.

NUM URI

NUM data is located with 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 follow typical URI syntax Content on another site. but re-purpose the port to indicate the module number. 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, e.g.: john.smith@numexample.com/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.

The subdomain www and the trailing dot (.) in a fully qualified domain name (FQDN) must be removed from NUM URIs by Clients. The NUM URI www.numexample.com, www.numexample.com. and numexample.com. must be equivalent.

NUM Record

NUM records are supported by all existing DNS infrastructure and can be created on any DNS server. NUM records can be created using DNS management tools provided by all cloud DNS providers and most domain name registrars.

Resource Record Type

A NUM record is a standard DNS TXT resource record.

Record Format

NUM records must be written in MODL Content on another site. – a compact data serialisation language well suited to storing objects in the DNS. NUM records must specify a version number using the syntax @n=<version-number>, the current version number is 1.

Due to DNS TXT record limitations, NUM records that exceed 255 characters in length must be split into multiple TXT record strings. To help overcome limits imposed by some DNS implementations, very large NUM records may be stored as record sets Content further down this document..

Record Locations

NUM records for a particular module can be stored in two parts of the DNS, known as NUM Zones: the Independent NUM Zone and the Hosted NUM Zone. Custom NUM records (records not based on a module) can only be stored in the Independent NUM Zone.

Independent NUM Zone

The Independent NUM Zone is found on the authoritative nameserver for the NUM Domain Content further up this document. under the label _num. The Independent NUM Zone for numexample.com and alice@numexample.com is _num.numexample.com.

Hosted NUM Zone

All Hosted NUM Zones are stored in the DNS below the domain name num.net. The Hosted NUM Zone for numexample.com and alice@numexample.com is _numexample.com.c.7.m.num.net. The NUM Server automatically deals with publishing and managing NUM records using a zone distribution technique Content further down this document..

NUM records can be created and managed using a simple interface provided by NUM Server Content on another site..

Email Section

NUM records for email addresses are stored in a separate section of the NUM Zone under the label e. Mailbox names (e.g. alice in alice@numexample.com) are prefixed with an underscore. The DNS name of an email section of a NUM Zone is built like this:

_<mailbox-name>.e.<num-zone>
The location of the email section of a NUM Zone

For example: _alice.e._num.numexample.com or _alice.e._numexample.com.c.7.m.num.net.

NUM Zones for IDNs

NUM records for Internationalized Domain Names (IDNs) are stored in the same way as any other domain. IDN standards Content on another site. dictate that domain names containing non-ASCII Content on another site. characters are stored within the DNS in Punycode Content on another site. format and prepended with the string xn--.

In the example num例.com ( is Chinese for example), the domain name is stored in the DNS as xn--num-xc0e.com and so the Indepdendent NUM Zone is at _num.xn--num-xc0e.com and the Hosted NUM Zone is at _xn--num-xc0e.com.n.f.5.num.net.

Record Hierarchy

NUM imposes no limit on the number of records that can be stored in a NUM Zone. There are two types of record:

Root Records

A NUM record returned for a NUM URI with no path (e.g. num://numexample.com:1/) is known as a root record. The root record for the Contacts module is known as the Contacts root record.

Branch Records

A NUM record returned for a NUM URI including a path (e.g. num://numexample.com:1/sales) is known as a branch record. Modules use branch records in different ways – some rely heavily on navigation between records (e.g. Contacts), others not at all.

NUM Record Sets

Some domain name registrars and DNS service providers set maximum limits on DNS TXT records (usually over 1000 characters). To overcome this limit, NUM records can be split over multiple resource records at the same DNS location, by creating a DNS Resource Record Set. The first record must start with the syntax <record-number>/<record-total>|, e.g. 1/3|. Each subsequent record must start with the syntax <record-number>|, e.g. 2|. In this example, we've set an arbitrary limit of 27 characters to demonstrate:

1._num 900 IN TXT "1/3|@n=1;o(n=NUM Example Co" 1._num 900 IN TXT "2|;c[t=441270123456;tw=nume" 1._num 900 IN TXT "3|xampletweets;fb=numbook])"
An example NUM Record Set in a zone file for the URI num://rrset.numexample.com:1/

NUM imposes no limit on the number of records in a set but some DNS server and client implementations may have difficulties processing very large record sets.

Reserved Keys

Keys prefixed with @ may have special meaning.

The following keys are reserved for NUM, they are case sensitive:

Key Name Description
@n NUM Version This should be present in all NUM records, the value specifies the version of the NUM protocol.
@L Link Included in a NUM record to indicate that one part of a NUM record is linked to another NUM record Content further down this document..
@R Redirect Included in a NUM record to instruct the NUM library to redirect to another NUM lookup Content elsewhere on this site..

Some modules may also use JSON-LD reserved keywords Content on another site..

NUM Lookup

NUM URIs Content further up this document. are resolved using a NUM lookup, which involves a series of DNS TXT record queries. NUM lookups are made by NUM clients through NUM libraries Content elsewhere on this site.. The structure of a DNS query made as a result of a NUM Lookup is as follows:

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

This structure is explained by way of example in the following sections.

NUM Queries

A lookup for a custom record must only query the Independent NUM Zone. A lookup for a standardised record (one based on a module) must run queries to the Independent and Hosted NUM Zones.

Independent Record Query

A lookup for the URI num://numexample.com:1/ results in a query to the Independent NUM Zone:

  • Command Prompt
  • Terminal
nslookup -type=TXT 1._num.numexample.com
A Windows command to run a DNS query to the Independent NUM Zone for the URI num://numexample.com:1/
dig 1._num.numexample.com TXT
A Unix command to run a DNS query to the Hosted NUM Zone for the URI num://numexample.com:1/

All queries for records based on a module require a query to the Independent NUM Zone.

Hosted Record Query

If a valid NUM record is not returned from the Independent NUM Zone, a query must be made to the Hosted NUM Zone. Hosted records are always found below num.net. The DNS location of a hosted record is determined based on a zone distribution technique Content further down this document. to help spread resource record load.

A lookup for the URI num://numexample.com:1/ results in a query to the Hosted NUM Zone:

  • Command Prompt
  • Terminal
nslookup -type=TXT 1._numexample.com.c.7.m.num.net
A Windows command to run a DNS query to the Hosted NUM Zone for the URI num://numexample.com:1/
dig 1._numexample.com.c.7.m.num.net TXT
A Unix command to run a DNS query to the Hosted NUM Zone for the URI num://numexample.com:1/

All modules require a query to the Hosted NUM Zone.

Email Lookups

NUM Lookups for email addresses make queries to the email section Content further up this document. of the NUM Zone. A NUM Lookup for the URI num://alice@numexample.com:1/ first runs a query to the Independent NUM Zone:

  • Command Prompt
  • Terminal
nslookup -type=TXT 1._alice.e._num.numexample.com
A Windows command to run a DNS query in the Independent NUM Zone for the URI num://alice@numexample.com:1/
dig 1._alice.e._num.numexample.com TXT
A Unix command to run a DNS query in the Independent NUM Zone for the URI num://alice@numexample.com:1/

If a valid NUM record is not returned, a DNS query is made to the Hosted NUM Zone:

  • Command Prompt
  • Terminal
nslookup -type=TXT 1._alice.e._numexample.com.c.7.m.num.net
A Windows command to run a DNS query in the Hosted NUM Zone for the URI num://alice@numexample.com:1/
dig 1._alice.e._numexample.com.c.7.m.num.net TXT
A Unix command to run a DNS query for the Hosted NUM Zone for the URI num://alice@numexample.com:1/

If a zone distribution record Content further up this document. is returned by the independent or hosted query, a new query must be made using zone distribution Content further down this document.. If the hosted query fails, the lookup fails.

Branch Record Lookups

When a NUM URI includes a path, it requires a branch record lookup. The URI path must be converted to a DNS name as follows:

  1. Replace path separators (/) with dots
  2. Reverse the order of each part

For example, the URI num://numexample.com:1/foo/bar will result in the following DNS query to the Independent NUM Zone:

  • Command Prompt
  • Terminal
nslookup -type=TXT bar.foo.1._num.numexample.com
A Windows command to run a DNS query to the Independent NUM Zone for the URI num://numexample.com:1/foo/bar
dig bar.foo.1._num.numexample.com TXT
A Unix command to run a DNS query to the Independent NUM Zone for the URI num://numexample.com:1/foo/bar

If a valid NUM record is not returned, a DNS query is made to the Hosted NUM Zone:

  • Command Prompt
  • Terminal
nslookup -type=TXT foo.bar.1._numexample.com.c.7.m.num.net
A Windows command to run a DNS query to the Hosted NUM Zone for the URI num://numexample.com:1/foo/bar
dig foo.bar.1._numexample.com.c.7.m.num.net TXT
A Unix command to run a DNS query to the Hosted NUM Zone for the URI num://numexample.com:1/foo/bar

NUM Responses

NUM responses are returned by DNS servers to NUM clients. Queries to the Hosted NUM Zone will either return a NUM record or NXDOMAIN. In the event a query to the Hosted NUM Zone returns SERVFAIL, the query should be retried at least once.

Client Side Processing

A key principle of NUM is that minimal user data leaves the client. DNS queries derived from the NUM URI and the client IP are the only pieces of data that should be passed to the DNS resolver. Aside from anycast Content on another site. implementations, the same NUM records should be delivered to all users worldwide. These records are then interpreted client side and displayed to users depending on user variables, for example – a different Contacts record can be displayed to people of different countries or languages, this is achieved with redirects Content further down this document..

DNS Responses

DNS responses must be received within 1.5 seconds, otherwise should be considered a failure. DNS responses must have a return message of NOERROR (return code of 0) and must return resource record(s) of type TXT. Any DNS Server response other than NOERROR or returning records other than TXT must be considered a failure.

Record Sets

If the response contains a NUM record set Content further up this document. (more than one resource record) – the response must be assembled. Any record not starting with the syntax specified must be ignored. If a record in the set is missing or multiple records are found with the same record number, this must be considered a failure. In the example below, we've set an arbitrary limit of 27 characters to demonstrate. Notice there's no guarantee of the order in which records are returned:

;; ANSWER SECTION: 1._num.rrset.numexample.com. 900 IN TXT "2|;c[t=441270123456;tw=nume" 1._num.rrset.numexample.com. 900 IN TXT "1/3|@n=1;o(n=NUM Example Co" 1._num.rrset.numexample.com. 900 IN TXT "3|xampletweets;fb=numbook])"
An example NUM Record Set Response for the NUM URI num://rrset.numexample.com:1/

Multi-string TXT Records

Due to DNS TXT record limitations Content further down this document., the contents of records over 255 characters must be stored as multiple TXT strings containing no more than 255 characters. TXT records that contain multiple TXT strings must be concatenated by the NUM client.

Security Considerations

NUM is built on top of the DNS protocol, known issues with DNS related to security are addressed by technologies such as DoH Content on another site., DoT Content on another site. and DNSSEC (RFC 4033, RFC 4034, and RFC 4035). NUM is compatible with all of these technologies. Known issues related to user privacy are addressed in DPRIVE Content on another site.. The method of DNS resolution and the provider of a DNS resolver is a user decision.

Very careful consideration will be given to any module that provides payment or security information (e.g. bank details / PGP keys), NUM Records using these modules could be a target for attack.

A user request for the URI num://example.com results in two queries: the first to the DNS of the authoritative zone for the domain numexample.com and the second to the NUM Server under the domain num.net, in the case of numexample.com, NUM records will be served from _numexample.com.c.7.m.num.net.

The NUM Server is a DNS-based store of NUM records which can be published and updated using a user-friendly interface. To publish or update records for a given domain a user must prove rights to do so. These rights are established through industry standard techniques: DNS TXT record creation; webpage creation on the webserver; homepage HTML modification.

DNS Limitations

The DNS is ultra-fast and reliable because it's light weight and its data is distributed and cached globally. These strengths have enabled the DNS to scale gracefully with the exponential growth of the internet and are what make the DNS an ideal location to store structured data. However, these same strengths mean the DNS is not well suited to providing results local to a user or providing a large dataset.

The following sections explain how these limitations can be overcome.

TXT Record Limit

DNS TXT record strings can be no longer than 255 characters. However, a single DNS TXT record can be composed of more than one string, as per RFC1035 Content on another site. sections 3.3.14 and 3.3. All DNS implementations should support multi-string TXT records but domain administrators creating independent records should check with their domain registrar / DNS provider.

UDP Packet Limit

NUM records are DNS TXT records and are typically transported via the UDP protocol. The DNS UDP packet limit was originally 512 bytes but almost all DNS clients and resolvers now accept UDP packets over 512 bytes through EDNS Content on another site.. Much larger DNS packets can be sent and received via TCP, but this may not be supported by all DNS clients, resolvers and servers.

To ensure maximum efficiency and compatibility with all hardware and software, it is recommended that NUM record responses are limited to 512 bytes where possible. This includes the DNS packet header and fully qualified domain name. The NUM record limit for the domain numexample.com is calculated as follows:

512 bytes (UDP packet limit) - 30 bytes (DNS response header not including domain or TXT resource record header) - domain length, in this example: (length of NUM record domain, not including trailing dot) e.g. '1._numexample.com.c.7.m.num.net' (31 characters) - number of TXT strings, in this example: 2 = 449 characters available for NUM record 1 character = 1 byte Quote marks around TXT records do not count towards the limit. DNS escape characters (\) do not count towards the limit.
Calculating the maximum length of a NUM record for numexample.com, staying within the UDP packet limit.

Due to the efficiencies of the MODL language Content on another site., a huge amount of data can be contained within a 512 byte NUM record.

Local Results

As the DNS is cached globally and no user data leaves the client, NUM is not well suited to returning data based on a user's location. Some modules use conditional logic to display different records to users dependent on their country and this can work well but showing records dependent on distance (for example your closest store) is more challenging. For example, a large nationwide brand might like to use the Contacts module to store contact data about each of their 5,000 stores. NUM is well suited to storing the data – requiring 5,000 branch records, but it is not well suited to searching that data or for example, ordering it based on distance to the user. Third party services would be required for this.

Time Sensitive Results

DNS caching means NUM is best suited to data which changes relatively rarely – perhaps no more than once a week and certainly no more than once a day. NUM is ideally suited to some use cases e.g. contact data; and terribly suited to others e.g. live stock prices.

Zone Distribution Technique

Most DNS server implementations limit the size of a zone file and many DNS cloud providers limit the number of resource records that can be stored in a zone – for example, AWS Route 53, Google Cloud DNS and Azure Cloud DNS all set default limits of 10,000 resource records per zone. The vast majority of businesses would never reach these limits, but the largest businesses might. To ensure NUM is massively scalable, fast and reliable we have developed a zone distribution technique to spread records across multiple zones where necessary. This technique is used by the NUM Server to serve out responses for millions of domain names. It can also be deployed independently when hosting NUM records for a huge number of email users on the same domain.

Hosted Zone

For hosted record queries, the domain (after punycoding for an IDN Content further up this document.) is hashed using the SHA-1 algorithm Content on another site. and then Base36 Content on another site. encoded, it's truncated to 3 characters and these three characters are split into labels prepending num.net in reverse order.

Hash the domain name being queried: SHA1(numexample.com) => be165e855fc34cee0cdfd1b68921152132ee9191 Encode the resulting hash to 36 characters (numbers and letters): base36(be165e855fc34cee0cdfd1b68921152132ee9191) => m7ct1u980ojlltm9sz0iz2qkbahgjv5 Take first three characters of hash: m, 7 and c Prefix the characters as labels to the NUM Server zone in reverse order: c.7.m.num.net Prefix the domain being queried with an underscore and prefix to the DNS name above: _numexample.com.c.7.m.num.net
An explanation of how to build the DNS name of the Hosted NUM Zone.

Email Section

Zone distribution in the email section of a NUM Zone is optional and can be deployed at 1-3 levels, this is only required for NUM Domains with tens of thousands of email addresses.

Zone Distribution Record

To store many thousands of NUM records for email addresses on the same domain, a wildcard DNS record must be setup at the root of the email section (below e), specifying the level of zone distribution being used. An example zone distribution record in zone file format:

*.e._num IN TXT "@n=1;zd=1"
An example wildcard record instructing clients to use a zone distribution query.

The zd key indicates the levels of zone distribution required for email queries. The value must be 1-3.

Take the value of the zd key returned by the original email query, e.g.: zd=3 Hash the mailbox name being queried: SHA1(john.smith) => 1b336c35b582810bac8821c5eae55a0637c3f8fd Encode the resulting hash to 36 characters (numbers and letters): base36(1b336c35b582810bac8821c5eae55a0637c3f8fd) => 36dv550mzh8mgmznspzwe1olapskbul Take first X characters of hash, where X is the value of the 'zd' key above: 3, 6 and d Prefix the characters as labels to the email section of the NUM Zone in reverse order: d.6.3.e._num.numexample.com Prefix the mailbox being queried with an underscore and prefix to the domain above: _john.smith.d.6.3.e._num.numexample.com
An explanation of the zone distribution technique available for the email section of NUM Zones.

Email record distribution is used on the NUM Server for some domains, e.g. large email providers like Gmail. When activated, it must be combined with NUM Server record distribution.