dns_json (dns_erlang v5.0.5)

View Source

This document describes the JSON encoding format for all DNS record types.

Format Structure

Resource Records (RR)

Resource records (dns_rr) are encoded as follows:

{
  "name": "example.com",
  "type": "A",
  "class": "in",
  "ttl": 3600,
  "data": {
    "ip": "192.168.1.1"
  }
}

The format includes:

  • name: Domain name (binary)
  • type: DNS type name as uppercase string (e.g., "A", "AAAA", "MX")
  • ttl: Time to live (integer)
  • data: Map containing the record-specific fields
  • class: Optional, only included if not IN (default)

Other Records

Non-RR records (message, query, OPT records) use a two-level nested map format:

  • Outer key: Record type identifier (descriptive name)
  • Inner map: Record fields with binary keys

Field Encoding Rules

  • IP addresses: String format ("192.168.1.1", "2001:db8::1")
  • Base64: Certificates, keys, signatures, MACs
  • Base16 (hex): Digests, hashes, fingerprints, addresses
  • Base32: NSEC3 hash
  • Domain names: Binary (dname format)
  • Lists: Arrays of converted values

Record Types

MESSAGE (dns_message) RFC1035

JSON Key: message

Fields:

{
  "message": {
    "id": 0,
    "qr": false,
    "oc": false,
    "aa": false,
    "tc": false,
    "rd": false,
    "ra": false,
    "ad": false,
    "cd": false,
    "rc": "value",
    "qc": 0,
    "anc": 0,
    "auc": 0,
    "adc": 0,
    "questions": [],
    "answers": [],
    "authority": [],
    "additional": []
  }
}

QUERY (dns_query) RFC1035

JSON Key: query

Fields:

{
  "query": {
    "name": "example.com",
    "class": 0,
    "type": 0
  }
}

A (dns_rrdata_a) RFC1035

Format: RRDATA fields (used within dns_rr.data)

Fields:

{
    "ip": "192.168.1.1"
}

Note: This format is used within the data field of dns_rr records.

AAAA (dns_rrdata_aaaa) RFC3596

Format: RRDATA fields (used within dns_rr.data)

Fields:

{
    "ip": "192.168.1.1"
}

Note: This format is used within the data field of dns_rr records.

AFSDB (dns_rrdata_afsdb) RFC1183

Format: RRDATA fields (used within dns_rr.data)

Fields:

{
    "subtype": 0,
    "hostname": "example.com"
}

Note: This format is used within the data field of dns_rr records.

CAA (dns_rrdata_caa) RFC6844

Format: RRDATA fields (used within dns_rr.data)

Fields:

{
    "flags": 0,
    "tag": "base64-encoded-data",
    "value": "base64-encoded-data"
}

Note: This format is used within the data field of dns_rr records.

CDNSKEY (dns_rrdata_cdnskey) RFC7344

Format: RRDATA fields (used within dns_rr.data)

Fields:

{
    "flags": 0,
    "protocol": 0,
    "alg": 0,
    "public_key": "base64-encoded-data",
    "keytag": 0
}

Note: This format is used within the data field of dns_rr records.

CDS (dns_rrdata_cds) RFC7344

Format: RRDATA fields (used within dns_rr.data)

Fields:

{
    "keytag": 0,
    "alg": 0,
    "digest_type": 0,
    "digest": "base16-encoded-data"
}

Note: This format is used within the data field of dns_rr records.

CERT (dns_rrdata_cert) RFC4398

Format: RRDATA fields (used within dns_rr.data)

Fields:

{
    "type": 0,
    "keytag": 0,
    "alg": 0,
    "cert": "base64-encoded-data"
}

Note: This format is used within the data field of dns_rr records.

CNAME (dns_rrdata_cname) RFC1035

Format: RRDATA fields (used within dns_rr.data)

Fields:

  • dname (dns:dname/0): Binary data (dname format) Example:
{
    "dname": "example.com"
}

Note: This format is used within the data field of dns_rr records.

CSYNC (dns_rrdata_csync) RFC7477

Format: RRDATA fields (used within dns_rr.data)

Fields:

{
    "soa_serial": "value",
    "flags": 0,
    "types": []
}

Note: This format is used within the data field of dns_rr records.

DHCID (dns_rrdata_dhcid) RFC4701

Format: RRDATA fields (used within dns_rr.data)

Fields:

  • data (binary/0): Base64-encoded data Example:
{
    "data": "base64-encoded-data"
}

Note: This format is used within the data field of dns_rr records.

DLV (dns_rrdata_dlv) RFC4431

Format: RRDATA fields (used within dns_rr.data)

Fields:

{
    "keytag": 0,
    "alg": 0,
    "digest_type": 0,
    "digest": "base16-encoded-data"
}

Note: This format is used within the data field of dns_rr records.

DNAME (dns_rrdata_dname) RFC6672

Format: RRDATA fields (used within dns_rr.data)

Fields:

  • dname (dns:dname/0): Binary data (dname format) Example:
{
    "dname": "example.com"
}

Note: This format is used within the data field of dns_rr records.

DNSKEY (dns_rrdata_dnskey) RFC4034

Format: RRDATA fields (used within dns_rr.data)

Fields:

{
    "flags": 0,
    "protocol": 0,
    "alg": 0,
    "public_key": "base64-encoded-data",
    "keytag": 0
}

Note: This format is used within the data field of dns_rr records.

DS (dns_rrdata_ds) RFC4034

Format: RRDATA fields (used within dns_rr.data)

Fields:

{
    "keytag": 0,
    "alg": 0,
    "digest_type": 0,
    "digest": "base16-encoded-data"
}

Note: This format is used within the data field of dns_rr records.

DSYNC (dns_rrdata_dsync) RFC9859

Format: RRDATA fields (used within dns_rr.data)

Fields:

{
    "rrtype": "value",
    "scheme": 0,
    "port": 0,
    "target": "target.example.com"
}

Note: This format is used within the data field of dns_rr records.

EUI48 (dns_rrdata_eui48) RFC7043

Format: RRDATA fields (used within dns_rr.data)

Fields:

  • address (<<_:48>>): Base16 (hex)-encoded address Example:
{
    "address": "base16-encoded-data"
}

Note: This format is used within the data field of dns_rr records.

EUI64 (dns_rrdata_eui64) RFC7043

Format: RRDATA fields (used within dns_rr.data)

Fields:

  • address (<<_:64>>): Base16 (hex)-encoded address Example:
{
    "address": "base16-encoded-data"
}

Note: This format is used within the data field of dns_rr records.

HINFO (dns_rrdata_hinfo) RFC1035

Format: RRDATA fields (used within dns_rr.data)

Fields:

  • cpu (binary/0): Binary data (dname format)
  • os (binary/0): Binary data (dname format) Example:
{
    "cpu": "value",
    "os": "value"
}

Note: This format is used within the data field of dns_rr records.

HTTPS (dns_rrdata_https)

Format: RRDATA fields (used within dns_rr.data)

Fields:

{
    "svc_priority": 0,
    "target_name": "value",
    "svc_params": {"alpn": ["h2", "h3"], "port": 443}
}

Note: This format is used within the data field of dns_rr records.

IPSECKEY (dns_rrdata_ipseckey) RFC4025

Format: RRDATA fields (used within dns_rr.data)

Fields:

{
    "precedence": 0,
    "alg": 0,
    "gateway": "value",
    "public_key": "base64-encoded-data"
}

Note: This format is used within the data field of dns_rr records.

KEY (dns_rrdata_key) RFC2535

Format: RRDATA fields (used within dns_rr.data)

Fields:

{
    "type": 0,
    "xt": 0,
    "name_type": 0,
    "sig": "value",
    "protocol": 0,
    "alg": 0,
    "public_key": "base64-encoded-data"
}

Note: This format is used within the data field of dns_rr records.

KX (dns_rrdata_kx) RFC2230

Format: RRDATA fields (used within dns_rr.data)

Fields:

{
    "preference": 0,
    "exchange": "mail.example.com"
}

Note: This format is used within the data field of dns_rr records.

LOC (dns_rrdata_loc) RFC1876

Format: RRDATA fields (used within dns_rr.data)

Fields:

{
    "size": "value",
    "horiz": "value",
    "vert": "value",
    "lat": "value",
    "lon": "value",
    "alt": "value"
}

Note: This format is used within the data field of dns_rr records.

MB (dns_rrdata_mb) RFC1035

Format: RRDATA fields (used within dns_rr.data)

Fields:

  • madname (dns:dname/0): Binary data (dname format) Example:
{
    "madname": "value"
}

Note: This format is used within the data field of dns_rr records.

MG (dns_rrdata_mg) RFC1035

Format: RRDATA fields (used within dns_rr.data)

Fields:

  • madname (dns:dname/0): Binary data (dname format) Example:
{
    "madname": "value"
}

Note: This format is used within the data field of dns_rr records.

MINFO (dns_rrdata_minfo) RFC1035

Format: RRDATA fields (used within dns_rr.data)

Fields:

{
    "rmailbx": "value",
    "emailbx": "value"
}

Note: This format is used within the data field of dns_rr records.

MR (dns_rrdata_mr) RFC1035

Format: RRDATA fields (used within dns_rr.data)

Fields:

  • newname (dns:dname/0): Binary data (dname format) Example:
{
    "newname": "value"
}

Note: This format is used within the data field of dns_rr records.

MX (dns_rrdata_mx) RFC1035

Format: RRDATA fields (used within dns_rr.data)

Fields:

{
    "preference": 0,
    "exchange": "mail.example.com"
}

Note: This format is used within the data field of dns_rr records.

NAPTR (dns_rrdata_naptr) RFC3403

Format: RRDATA fields (used within dns_rr.data)

Fields:

{
    "order": "value",
    "preference": 0,
    "flags": 0,
    "services": "value",
    "regexp": "value",
    "replacement": "value"
}

Note: This format is used within the data field of dns_rr records.

NS (dns_rrdata_ns) RFC1035

Format: RRDATA fields (used within dns_rr.data)

Fields:

  • dname (dns:dname/0): Binary data (dname format) Example:
{
    "dname": "example.com"
}

Note: This format is used within the data field of dns_rr records.

NSEC (dns_rrdata_nsec) RFC4034

Format: RRDATA fields (used within dns_rr.data)

Fields:

{
    "next_dname": "value",
    "types": []
}

Note: This format is used within the data field of dns_rr records.

NSEC3 (dns_rrdata_nsec3) RFC5155

Format: RRDATA fields (used within dns_rr.data)

Fields:

{
    "hash_alg": 0,
    "opt_out": false,
    "iterations": 0,
    "salt": "base16-encoded-data",
    "hash": "base32-encoded-data",
    "types": []
}

Note: This format is used within the data field of dns_rr records.

NSEC3PARAM (dns_rrdata_nsec3param) RFC5155

Format: RRDATA fields (used within dns_rr.data)

Fields:

{
    "hash_alg": 0,
    "flags": 0,
    "iterations": 0,
    "salt": "base16-encoded-data"
}

Note: This format is used within the data field of dns_rr records.

NXT (dns_rrdata_nxt) RFC2535

Format: RRDATA fields (used within dns_rr.data)

Fields:

{
    "dname": "example.com",
    "types": []
}

Note: This format is used within the data field of dns_rr records.

OPENPGPKEY (dns_rrdata_openpgpkey) RFC7929

Format: RRDATA fields (used within dns_rr.data)

Fields:

  • data (binary/0): Base64-encoded data Example:
{
    "data": "base64-encoded-data"
}

Note: This format is used within the data field of dns_rr records.

PTR (dns_rrdata_ptr) RFC1035

Format: RRDATA fields (used within dns_rr.data)

Fields:

  • dname (dns:dname/0): Binary data (dname format) Example:
{
    "dname": "example.com"
}

Note: This format is used within the data field of dns_rr records.

RESINFO (dns_rrdata_resinfo) RFC9606

Format: RRDATA fields (used within dns_rr.data)

Fields:

  • data ([binary/0]): Binary data (dname format) Example:
{
    "data": []
}

Note: This format is used within the data field of dns_rr records.

RP (dns_rrdata_rp) RFC1183

Format: RRDATA fields (used within dns_rr.data)

Fields:

{
    "mbox": "value",
    "txt": []
}

Note: This format is used within the data field of dns_rr records.

RRSIG (dns_rrdata_rrsig) RFC4034

Format: RRDATA fields (used within dns_rr.data)

Fields:

{
    "type_covered": "value",
    "alg": 0,
    "labels": "value",
    "original_ttl": "value",
    "expiration": "value",
    "inception": "value",
    "keytag": 0,
    "signers_name": "value",
    "signature": "base64-encoded-data"
}

Note: This format is used within the data field of dns_rr records.

RT (dns_rrdata_rt) RFC1183

Format: RRDATA fields (used within dns_rr.data)

Fields:

{
    "preference": 0,
    "host": "value"
}

Note: This format is used within the data field of dns_rr records.

SMIMEA (dns_rrdata_smimea) RFC8162

Format: RRDATA fields (used within dns_rr.data)

Fields:

{
    "usage": "value",
    "selector": "value",
    "matching_type": "value",
    "certificate": "base16-encoded-data"
}

Note: This format is used within the data field of dns_rr records.

SOA (dns_rrdata_soa) RFC1035

Format: RRDATA fields (used within dns_rr.data)

Fields:

{
    "mname": "ns1.example.com",
    "rname": "admin.example.com",
    "serial": 0,
    "refresh": 0,
    "retry": 0,
    "expire": 0,
    "minimum": 0
}

Note: This format is used within the data field of dns_rr records.

SPF (dns_rrdata_spf) RFC4408

Format: RRDATA fields (used within dns_rr.data)

Fields:

  • spf ([binary/0]): Binary data (dname format) Example:
{
    "spf": "value"
}

Note: This format is used within the data field of dns_rr records.

SRV (dns_rrdata_srv) RFC2782

Format: RRDATA fields (used within dns_rr.data)

Fields:

{
    "priority": 0,
    "weight": 0,
    "port": 0,
    "target": "target.example.com"
}

Note: This format is used within the data field of dns_rr records.

SSHFP (dns_rrdata_sshfp) RFC4255

Format: RRDATA fields (used within dns_rr.data)

Fields:

{
    "alg": 0,
    "fptype": "value",
    "fp": "base16-encoded-data"
}

Note: This format is used within the data field of dns_rr records.

SVCB (dns_rrdata_svcb) RFC9460

Format: RRDATA fields (used within dns_rr.data)

Fields:

{
    "svc_priority": 0,
    "target_name": "value",
    "svc_params": {"alpn": ["h2", "h3"], "port": 443}
}

Note: This format is used within the data field of dns_rr records.

TLSA (dns_rrdata_tlsa) RFC6698

Format: RRDATA fields (used within dns_rr.data)

Fields:

{
    "usage": "value",
    "selector": "value",
    "matching_type": "value",
    "certificate": "base16-encoded-data"
}

Note: This format is used within the data field of dns_rr records.

TSIG (dns_rrdata_tsig) RFC2845

Format: RRDATA fields (used within dns_rr.data)

Fields:

{
    "alg": 0,
    "time": "value",
    "fudge": "value",
    "mac": "base64-encoded-data",
    "msgid": "value",
    "err": "value",
    "other": "base16-encoded-data"
}

Note: This format is used within the data field of dns_rr records.

TXT (dns_rrdata_txt) RFC1035

Format: RRDATA fields (used within dns_rr.data)

Fields:

  • txt ([binary/0]): Binary data (dname format) Example:
{
    "txts": []
}

Note: This format is used within the data field of dns_rr records.

URI (dns_rrdata_uri) RFC7553

Format: RRDATA fields (used within dns_rr.data)

Fields:

{
    "priority": 0,
    "weight": 0,
    "target": "target.example.com"
}

Note: This format is used within the data field of dns_rr records.

WALLET (dns_rrdata_wallet)

Format: RRDATA fields (used within dns_rr.data)

Fields:

  • data (binary/0): Base64-encoded data Example:
{
    "data": "base64-encoded-data"
}

Note: This format is used within the data field of dns_rr records.

ZONEMD (dns_rrdata_zonemd) RFC8976

Format: RRDATA fields (used within dns_rr.data)

Fields:

{
    "serial": 0,
    "scheme": 0,
    "algorithm": 0,
    "hash": "base16-encoded-data"
}

Note: This format is used within the data field of dns_rr records.

JSON Key: unknown

Fields:

  • client (<<_:64>>): Direct value
  • server (<<_:64, _:_*8>>): Direct value Example:
{
  "unknown": {
    "client": "value",
    "server": "value"
  }
}

OPTECS (dns_opt_ecs) RFC7871

JSON Key: unknown

Fields:

  • family (dns:uint16/0): Base16 (hex)-encoded binary
  • source_prefix_length (dns:uint8/0): Base16 (hex)-encoded binary
  • scope_prefix_length (dns:uint8/0): Base16 (hex)-encoded binary
  • address (binary/0): Base16 (hex)-encoded address Example:
{
  "unknown": {
    "family": "base16-encoded-data",
    "source_prefix_length": "base16-encoded-data",
    "scope_prefix_length": "base16-encoded-data",
    "address": "base16-encoded-data"
  }
}

OPTEDE (dns_opt_ede) RFC8914

JSON Key: unknown

Fields:

{
  "unknown": {
    "info_code": "value",
    "extra_text": "value"
  }
}

OPTLLQ (dns_opt_llq) RFC8764

JSON Key: unknown

Fields:

{
  "unknown": {
    "opcode": "value",
    "errorcode": "value",
    "id": 0,
    "leaselife": "value"
  }
}

OPTNSID (dns_opt_nsid) RFC5001

JSON Key: unknown

Fields:

  • data (binary/0): Base16 (hex)-encoded data Example:
{
  "unknown": {
    "data": "base16-encoded-data"
  }
}

OPTOWNER (dns_opt_owner)

JSON Key: unknown

Fields:

  • seq (dns:uint8/0): Base16 (hex)-encoded binary
  • primary_mac (<<_:48>>): Base16 (hex)-encoded binary

  • wakeup_mac (<<>> | <<_:48>>): Base16 (hex)-encoded binary

  • password (<<>> | <<_:48>>): Base16 (hex)-encoded binary Example:

{
  "unknown": {
    "seq": "base16-encoded-data",
    "primary_mac": "base16-encoded-data",
    "wakeup_mac": "base16-encoded-data",
    "password": "base16-encoded-data"
  }
}

OPTUL (dns_opt_ul)

JSON Key: unknown

Fields:

{
  "unknown": {
    "lease": "value"
  }
}

OPTUNKNOWN (dns_opt_unknown)

JSON Key: OPT_UNKNOWN

Fields:

{
  "OPT_UNKNOWN": {
    "id": 0,
    "bin": "base16-encoded-data"
  }
}

OPTRR (dns_optrr) RFC6891

JSON Key: OPT

Fields:

{
  "OPT": {
    "udp_payload_size": "value",
    "ext_rcode": "value",
    "version": "value",
    "dnssec": "value",
    "data": []
  }
}

RR (dns_rr) RFC1035

Fields:

  • name (dns:dname/0): Domain name (binary, dname format)
  • type (dns:type/0): DNS type name as uppercase binary string (e.g., "A", "AAAA", "MX")
  • class (dns:class/0): DNS class name as uppercase binary string (e.g., "IN", "CH", "HS") - optional, defaults to "IN" if omitted
  • ttl (dns:ttl/0): Time to live (integer)
  • data (dns:rrdata/0): Map containing the RRDATA-specific fields (see individual RRDATA record types below) Example:
{
  "name": "example.com",
  "type": "A",
  "class": "IN",
  "ttl": 3600,
  "data": {
    "ip": "192.168.1.1"
  }
}

Note: The data field contains the RRDATA-specific fields. The class field is optional and defaults to "IN" if omitted. See individual RRDATA record types below for complete field documentation.

SVCB Service Parameters

The svc_params field in SVCB and HTTPS records is a map containing service binding parameters as defined in RFC 9460.

NOTE

The keys keyN when N ranges from 0 to 6 are equivalent to their named counterparts and will be validated accordingly.

Parameters:

  • mandatory ([string()]): List of parameter names that must be present (e.g., ["alpn", "port"]).
  • alpn ([binary()]): List of ALPN protocol identifiers as decoded binaries (e.g., ["h2", "h3"])
  • no-default-alpn (null): Indicates that no default ALPN should be used.
  • port (integer()): Port number (0-65535)
  • ipv4hint ([string()]): List of IPv4 addresses as strings (e.g., ["192.168.1.1", "192.168.1.2"])
  • ipv6hint ([string()]): List of IPv6 addresses as strings (e.g., ["2001:db8::1"])
  • ech (binary()): Encrypted ClientHello (ECH) configuration as decoded binary

  • keyNNNN (binary() | null): Unknown parameters where NNNN is the parameter key number (0-65535). In JSON the key is the string "key" followed by the decimal number (e.g. "key65001"). The value is either a binary (as string) or null for no-value parameters.

Example:

{
    "svc_priority": 1,
    "target_name": "target.example.com",
    "svc_params": {
        "mandatory": ["alpn", "port"],
        "alpn": ["h2", "h3"],
        "port": 443,
        "ipv4hint": ["192.168.1.1", "192.168.1.2"],
        "ipv6hint": ["2001:db8::1"],
        "ech": "ech-config-data",
        "key65001": "custom-param-value",
        "key65002": null
    }
}

Note: All parameter values are in their decoded/native format (not base64-encoded). Binary values like ALPN identifiers and ECH config are provided as raw binaries, not base64 strings.

Summary

Functions

from_map/1

Converts a map representation back to a DNS record.

to_map/1

Converts a DNS record to a map representation suitable for JSON encoding.

Functions

from_map/1

(since v5.0.0) 
-spec from_map(map()) -> tuple().

Converts a map representation back to a DNS record.

to_map/1

(since v5.0.0) 
-spec to_map(tuple()) -> map().

Converts a DNS record to a map representation suitable for JSON encoding.