Skip to content
Control Plane Labs
Search

URI record

Publishes a service URI, optionally with priority and weight, so a client can discover an endpoint without a fixed hostname or port.

Written and maintained by Ben Ennis

Last reviewed July 27, 2026 · How we verify this

Zone-file example

example.com. 3600 IN URI 10 1 "https://status.example.com/"

Typical uses

  • DNS-based service discovery for applications that need a URI rather than only a host and port
  • Publishing web, API, and other endpoint locations under a domain-controlled namespace
  • Migrating a service while allowing clients to rank several destinations
  • Sharing a discovery record with systems that already understand SRV-style priority and weight

When it breaks, check

  • The priority and weight fields are decimal integers before the quoted URI
  • The URI is a character-string value; quote it and escape characters required by the zone-file format
  • A resolver can return the record, but the application still has to implement URI-record discovery
  • Do not assume browsers or generic HTTP clients will consult URI records automatically

What the URI record does

A URI record is a discovery record for protocols that need more than an address. The owner name identifies the service’s namespace, while the RDATA supplies a URI that the application can interpret. Priority works like SRV priority: clients should try the lowest value first. Weight distributes selection among records with the same priority.

This is deliberately not a universal redirect. A DNS resolver returns the record as data, and no ordinary browser navigation follows it merely because it exists. The application must define the lookup name, validate the returned scheme, and decide whether the URI is acceptable for the operation. That separation is useful for service discovery, but it is also why adding a URI record alone does not change existing client behaviour.

Zone-file and wire format

The RDATA contains three fields: priority weight target. Priority and weight are unsigned decimal integers, followed by a URI encoded as a quoted character-string. The URI can include a scheme, authority, path, query, or fragment according to the consuming protocol. Multiple records give the client alternatives; do not put an HTTP URL in the target field without the quotes, because a zone parser will treat punctuation as syntax.

; owner                  TTL  class type  priority weight URI
example.com.              3600 IN   URI   10       1      "https://status.example.com/"
example.com.              3600 IN   URI   20       1      "https://status-backup.example.com/"

Common uses

URI records fit systems that already have a DNS namespace and need a protocol-specific endpoint. A deployment controller can publish a service’s API URI, a client can choose among regional endpoints, and an operator can change the destination without changing every configuration file. Use them when the consuming software explicitly defines the lookup name and URI grammar. For a generic hostname-to-address lookup, use A or AAAA; for a host-and-port service, compare SRV first.

Troubleshooting

Start by asking for the exact owner name and record class. A successful dig URI response only proves that the zone serves the data; it does not prove that the application performs the lookup. Confirm the quoted URI survived the provider’s UI, especially characters such as semicolons, spaces, and backslashes. Then test the URI with the application’s own discovery path and validate that its scheme and host are allowed.

If clients see an old answer, inspect the record’s TTL and every authoritative nameserver. A recursive resolver can cache the old set until that TTL expires.

dig example.com URI +noall +answer

# Ask each authoritative server for the same owner.
dig @ns1.example.net example.com URI +noall +answer
dig @ns2.example.net example.com URI +noall +answer

The defining RFC

URI is DNS type 256, defined by RFC 7553. The specification defines the priority and weight selection fields and leaves the URI’s application meaning to the protocol that consumes it. The record is part of the IANA DNS Parameters registry. A service that needs authenticated discovery should also consider DNSSEC validation and an application-level allowlist; publication in DNS is not proof that an endpoint is safe. The DNS lookup tool can confirm the wire response, but it cannot infer whether a client supports URI discovery.

Reference and tooling

Every record type and its assigned numeric value is listed in theIANA DNS Parameters registry. To query a live zone from the browser, use theDNS lookup tool. If the record you are chasing is TLS-related, the TLS inspector andCertificate Transparency lookup are usually the next two stops.

Other record types