Module Specification: Contacts
Introduction
Contact information on the internet is unstructured and inconsistent. Finding contact information on an organisation's website consumes considerable amounts of time, data, and often requires significant user interaction. Contact information provided by search engines and social media platforms is neither open nor authoritative and is often incomplete and inaccurate.
The Contacts module can be used to store contact data for a person, group, organisation, department, employee, location or folder. Data can be stored hierarchically allowing organisations to store contact information for each of their locations, departments and employees.
Branch records can be used to navigate complex contact information, providing structured machine readable data to help navigate a call centre or support teams.
Status
The Contacts module is currently being finalised, we are inviting members of the technical community to provide feedback on the specification.
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 .
Links in This Document
For the benefit of readers, these icons are displayed next to links to indicate where the link leads:




Author
The Contacts module was created by Elliott Brown .
Working with Contact Records
The first step for working with a NUM Contacts record is to turn it into a useful object.
Creating the Object
NUM records are written in MODL and are unpacked into objects by a MODL interpreter with the help of a NUM record configuration file. To successfully unpack the MODL object we must write a MODL string including user variables, the record configuration file and the NUM record itself.
Adding User Variables
The following user variables can be used:
ID | Name | Example | Example Explanation | Required |
_C | Country | gb | Country code in ISO 3166-1 alpha 2 ![]() |
Yes |
_L | Language | en | Language code in ISO 639-1 ![]() |
Yes |
_DV | Device | iPhone 7 | This is the model of the device. | No |
_OS | Operating System | iOS 10.3 | The operating system used by the device. | No |
_TZ | Time Zone | GMT | Time zone code. A list of time zones can be viewed here ![]() |
No |
_G | GPS Co-ordinates | 53.473997,-2.237334 | GPS Co-ordinates in WGS84 ![]() |
No |
Each user variable is assigned to a hidden object , using the key shown in the
ID
column. These variables make up the start of our MODL string:

Adding the Record Configuration File
After assiging values to user variables, we must use the MODL *load instruction to load the Contacts record configuration file, you can view it here
.

Adding the NUM Record
The final stage is to retrieve the NUM record from the DNS using a NUM lookup and add the record returned to our MODL string. In this example we've retreived a NUM record for the domain
numexample.com
:

Now we can interpret our MODL string and have a developer friendly unpacked object to work with.
Understanding the Object
NUM records for the Contacts module describe Entities.
NUM records can be both multi-national and multi-lingual, catering for huge corporations while staying within DNS limits . Contact records are designed to serve the needs of all domain owners – from individuals operating blogs, through to huge multi-national corporations with thousands of stores and a sprawling online presence.
Contact records can be organised hierarchically and linked together, enabling a user or machine to navigate structured contact information. Individuals and small organisations may find that they can provide all of their contact information to users in one simple root record.
Whilst it would be possible for many organisations to provide all of their contact information in one large root NUM record, some organisations prefer their contact information to be more organised and structured. For example, a multi-national organisation may need to present a different NUM record to customers in each of the countries they operate in. Some organisations may like to organise their contact information by department – e.g. Sales.
Entity
A NUM record can describe:
-
People using the key
person
-
Group using the key
group
-
Organisations using the key
organisation
-
Departments using the key
department
-
Employees using the key
employee
-
Locations using the key
location
All entities can be described using the following keys:
-
Name a string using the key
name
providing the name of the object -
Contacts, an array with the key
contacts
containing ways to contact the entity -
Available hours, a specially formatted
string or array using the key
hours
showing when the object is available
In addition to the keys above, it's also possible to describe:
-
A person with a short biographical profile, a string using the key
bio
-
A group with a description, a string using the key
description
-
An organisation with a motto or slogan, a string using the key
slogan
-
A department with a description, a string using the key
description
-
An employee with a job title / role, a string using the key
role
-
A location with a description, a string using the key
description
Contact Methods
An Entity can include contact methods within the contacts
list, contact methods can be described with:
-
Value, a string or array using the key
value
or an array with the keylines
in the case ofaddress
. -
Description, a string using the key
description
-
Available hours, a specially formatted
string or array using the key
hours
showing when the object is available
The NUM Contacts configuration file automatically adds the following data to each contact method to assist developers when displaying contact methods in clients:
-
Prefix, a string using the key
prefix
– typically used for URL schemes -
Description default, a string using the key
description_default
– a default value to use for contact methods that do not have adescription
-
Object Display Name, a string using the key
object_display_name
– providing a display friendly way to describe a method, e.g. "Telephone" -
Method Type, a string using the key
method_type
with the possible valuescore
andthird_party
. Core methods are those which are standardised contact methods and are not exclusive to other platforms, e.g. email, telephone, GPS etc. Third party methods are contact methods which are reliant on third parties – like Facebook, Twitter and more. -
Controller, a string using the key
controller
which identifies the entity in control of that contact method. For example, the controller of the Facebook contact method isfacebook.com
. This can be used to fetch an icon for each contact method. -
Value Prefix, a string using the key
value_prefix
which identifies the entity in control of that contact method. For example, the controller of the Facebook contact method isfacebook.com
. This can be used to fetch an icon for each contact method.
Links
Links are presented with the key link
and can include:
-
Description, a string using the key
description
-
@L, a NUM link
which instructs the client to make a further NUM lookup.
Special Formatting
Values for some objects adhere to formatting rules. These values must be interpreted by the NUM client.
Available Hours
This value provides information about the hours that an object is available for during the day. The value is provided with the key av
and it can be used to describe any object. This is the field syntax:

Multiple values can be supplied. Settings that are defined later in the array override those defined earlier. In this example, the first setting sets available hours to weekdays 9am - 5pm but the second setting overrides that for Mondays, declaring available hours on Monday as midday - 6pm London time.


- JSON
- MODL
Day Descriptor
The day descriptor field offers a range of options:
Descriptor | Explanation | Example | Outcome |
d | Every day | [email protected]@LON | Available every day 9am - 5pm |
wd | Weekdays | [email protected]@LON | Available weekdays 9am - 5pm |
we | Weekend | [email protected]@LON | Available Saturday and Sunday 9am - 5pm |
1 | Monday | [email protected]@LON | Available Monday 9am - 5pm |
2 | Tuesday | [email protected]@LON | Available Tuesday 9am - 5pm |
3 | Wednesday | [email protected]@LON | Available Wednesday 9am - 5pm |
4 | Thursday | [email protected]@LON | Available Thursday 9am - 5pm |
5 | Friday | [email protected]@LON | Available Friday 9am - 5pm |
6 | Saturday | [email protected]@LON | Available Saturday 9am - 5pm |
7 | Sunday | [email protected]@LON | Available Sunday 9am - 5pm |
nh | National holidays (user country) | [email protected]@LON | Closed on national holidays in the country of the user. |
nhcountry | National holidays (specified country) | [email protected]@NYC | Closed on national holidays of the United States. |
dayno-dayno | Day range | [email protected]@LON | Open Monday - Thursday 9am - 5pm |
dayno,dayno | Day list | 1,3,[email protected]@LON | Open Monday, Wednesday and Friday 9am - 5pm |
YYYYMMDD | A specified day | [email protected]@LON | Closed on 11th December 2018 |
YYYYMMDD-YYYYMMDD | A specified date range | [email protected]@LON | Closed from 19th December 2018 through to 2nd January 2019 |
Time Descriptor
Times must be provided in 24-hour format but are flexible to ensure maximum character efficiency. Both a start time and end time must be set.
Example | Explanation |
9-17 9.00-17 9.00.00-17.00 09.00.00-17
|
All are valid and represent exactly 9 AM until 5 PM. The object will be shown as available at 9am and unavailable at 5pm. |
9.30-17.30 9.30-17.30 9.30.00-17.30.00 09.30.00-17.30
|
All are valid and represent exactly 9:30 AM until 5:30 PM. The object will be shown as available at 09:30 and unavailable at 17:30. |
Midnight for the start time (start of the day) is 0
. Midnight for the end time (end of the day) is 24
. Multiple time ranges can be supplied for a day descriptor by separating the times with a comma (,
). This can be particularly useful if a location is closed for a brief period during the day, e.g. a lunch hour.
In this example, available hours are set 9am until midday, unavailable between midday and 1pm, available from 1pm until 5pm:


- JSON
- MODL