What Is a Machine-Readable Identity Record? With an Example

A machine-readable identity record describes an agent, service, or system in structured fields that software can parse. It identifies the subject and can connect it to operator information, declared capabilities, official resources, and evidence about particular claims.

For a customer, your service might be a profile page with a clear description and a contact button. Another application needs values it can extract reliably: the name, the description, the documentation URL, and the address of the service it wants to use.

Headless Domains connects those records to a maintained public name. That gives people and compatible agents a common reference for the work you offer, even when its documentation or service moves.

What makes the record machine-readable?

A parser needs a defined structure. JSON, for example, represents data through objects, arrays, strings, numbers, and other defined values. Software can extract a named field without interpreting where a designer placed it on a page.

But valid JSON is only the beginning. The receiving application also needs to understand what the fields mean. A field called status might describe a registration, a service, or a particular job. Those are different subjects.

A useful record therefore follows a documented schema or agreed format. That contract defines the fields, their types, and their meaning. Its version helps clients recognize which structure they are reading.

Two files called agent.json can use different schemas. The filename does not make them interchangeable. Our agent.json introduction explains the Headless Domains manifest specifically.

The information a useful identity record connects

Start with what a prospective caller needs to understand the service. The exact field names depend on the format you use, but these are useful categories:

• Identity: the public name or identifier of the agent, service, operator, or resource being described.
• Purpose: a description and supported capability information that explain what someone can request.
• Operator: appropriate public information about who publishes or operates the service, with a contact route.
• Resources: references to documentation, manifests, workflow instructions, and service interfaces where relevant.
• Status and evidence: information about the particular registration, service, or check, with its source and timing where the format supports them.

You do not need every protocol or an enormous manifest. A service that publishes a specification may need its approved document and maintainer information. A paid API needs different resources. Include what helps someone take the right next step.

A small example: naming a production service

Imagine a service called Manual Studio that prepares product manuals for review. Its public name could be manuals.factory. This is a fictional example; availability has not been checked.

A person might read: “Manual Studio prepares product manuals. Example Publishing operates the service, and its documentation explains the supported inputs.” Software can work with the same information as separate values:

{
  "public_name": "manuals.factory",
  "display_name": "Manual Studio",
  "operator_name": "Example Publishing",
  "description": "Prepares product manuals for review.",
  "documentation_url": "https://example.com/manual-studio/docs"
}

This teaching example uses illustrative field names. It is not a Headless Domains API payload, a complete manifest, or a universal identity schema. For a real integration, use the documented format your publisher and client support.

The distinction between the two names is useful. Manual Studio is a display label; manuals.factory is the example's designated public identity. Neither has to match the hostname serving its documentation.

A compatible application can extract the documentation address and decide what to retrieve next. It still needs the documentation to explain the service, and the operator to keep it accurate.

How Headless Domains connects the name and the records

Headless Domains provides the public naming and discovery layer. Its manifest documentation describes hosted JSON manifests and Markdown capability records, with DNS TXT pointers connecting the name to those files.

The documented pointer labels are agent-manifest= for the JSON manifest and skill-md= for the Markdown record. Hosted addresses follow these patterns:

https://headlessdomains.com/manifests/<domain>.json
https://headlessdomains.com/skills/<domain>.md

Follow the actual links published for your registered name. A headless domain does not automatically become an ordinary browser address with every associated file hosted beneath it. Direct Handshake DNS resolution requires compatible resolution support; the platform also supplies public HTTPS APIs.

The Headless Domains machine instructions describe the canonical read-only resolver at /api/v1/resolve/{domain}. Compatible clients can use it to locate public identity information and linked resources. Discovering an action through that response does not authorize or execute it.

This separation lets you keep the runtime and website you already use. The maintained name connects callers to the current information about your service.

The record points to instructions and interfaces

A machine-readable identity record can connect several documents without turning them into the same thing.

A profile introduces the service to people. A workflow document explains a task. An API description supplies an interface contract. An A2A Agent Card supplies metadata defined by the A2A protocol. An MCP server exposes supported protocol capabilities to its clients.

The identity record helps a caller find the relevant resource. The caller then needs to support that resource's format, protocol, and access requirements.

For help choosing which documents to publish, use our llms.txt, SKILL.md, and agent.json comparison. You can link to detail instead of copying an entire operating manual into the identity record.

Readable information and verified information are different

A record can be perfectly formatted and still contain an incorrect claim. An operator name is a published statement. Repeating it across a profile and manifest does not turn it into independent evidence.

Verification needs a defined subject and method. A signature can support a conclusion about a signing key and the data it signed. A working URL can show that something responded. Neither establishes every claim about the service.

Likewise, a recent retrieval time does not prove the information was recently reviewed. An active registration does not prove the agent is running. Clear records make these distinctions easier to inspect.

Our identity-record field guide covers that inspection process. Keep credentials, customer documents, private approvals, and internal operating data out of public records.

Give the work a name that fits

The value extends across Headless Domains namespaces. A .factory identity can describe a production service like Manual Studio. A .bpo identity can connect a repeatable business process to its offer and intake instructions. A .chatbot identity can point to the current interfaces for a conversational product.

Other work may fit .agent, .boss, .protocol, or .manifest. Choose the namespace around what people and other agents need to recognize. Then publish records that explain it.

As the service changes, maintain the registration and update its resource links. Customers can keep using the name while the record points to the current setup. The Agent Identity Stack explains how that public identity connects with the wider systems for credentials, access, and governance.

Common questions

Is every machine-readable identity record public?

No. Internal registries and identity systems also hold structured records. Publish a public record when people or external systems need to discover and inspect what you offer; keep sensitive operational details private.

Is JSON required?

No. JSON is one structured format. The important requirement is that the receiving software understands the record's structure and meaning. Use the format required by your integration.

Does a record grant access to tools or payments?

No. It can describe interfaces and point to authentication or payment instructions. The caller's authority and the receiving service's controls determine whether an action is allowed.

Does registering a headless domain complete the record?

Headless Domains documents generated records, but you still need to review the information and configure the service links you want to publish. A useful record describes what you actually operate.

Make your existing service easier to understand

Start with one thing you run. Give it a clear description, identify the responsible operator, and connect the name to its current public resources. If you already have a headless domain, improve that record first.

Give your assistant the Headless Domains instructions and ask it to help connect a fitting public identity to the service you already offer.