Entity-ID Resolver Specification

1. Scope

oneentity.id provides public resolver records for entities such as people and organizations. A resolver record is not a login account, social profile or verification badge. It is a public identifier record with a human-readable page and a machine-readable JSON-LD representation.

Registration, claiming and record management are handled separately through myentity.id. Public resolution happens on oneentity.id.

2. URL forms

Each public record can have two relevant URL forms: a human-readable resolver URL and a stable Entity @id URL.

People

Human-readable resolver URL:
https://oneentity.id/p/example-person

Stable Entity @id:
https://oneentity.id/p/p7ka-4m2q-x9vz#person

Organizations

Human-readable resolver URL:
https://oneentity.id/o/example-organization

Stable Entity @id:
https://oneentity.id/o/o8ra-7p3m-k2qx#organization

The resolver URL is designed for humans and public linking. The stable Entity @id is designed for structured data, knowledge graph references and systems that need a persistent entity identifier.

3. Representations

Public records are available as HTML and JSON-LD. The HTML representation includes embedded Schema.org JSON-LD. The JSON-LD representation exposes the structured graph directly.

HTML

GET /p/example-person
Accept: text/html

The server returns a human-readable HTML page with embedded JSON-LD.

JSON-LD by content negotiation

GET /p/example-person
Accept: application/ld+json

The server returns the JSON-LD representation with the content type application/ld+json; charset=utf-8.

JSON-LD by query parameter

GET /p/example-person?format=jsonld
GET /p/example-person?format=json

Query parameters are provided for clients that cannot set an Accept header. The canonical record URL remains the resolver URL.

4. Content types and response headers

Implementations should expect the following response types.

HTML:
Content-Type: text/html; charset=utf-8

JSON-LD:
Content-Type: application/ld+json; charset=utf-8

JSON-LD responses may include caching and negotiation headers such as:

ETag: "..."
Last-Modified: ...
Vary: Accept

Vary: Accept indicates that the same URL can return different representations depending on the request Accept header.

5. Redirect behavior

A stable UID path without a fragment may redirect to the current human-readable resolver URL.

GET /p/p7ka-4m2q-x9vz
301 -> /p/example-person

The stable Entity @id remains unchanged:

https://oneentity.id/p/p7ka-4m2q-x9vz#person

This separates the public page URL from the stable entity identifier. Slugs may be used for readability. Entity UIDs are intended to remain stable.

6. Structured data model

Public records use Schema.org JSON-LD. A person record typically contains a ProfilePage node and a Person node. An organization record typically contains an ItemPage node and an Organization node.

{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "ProfilePage",
      "@id": "https://oneentity.id/p/example-person#webpage",
      "url": "https://oneentity.id/p/example-person",
      "mainEntity": {
        "@id": "https://oneentity.id/p/p7ka-4m2q-x9vz#person"
      }
    },
    {
      "@type": "Person",
      "@id": "https://oneentity.id/p/p7ka-4m2q-x9vz#person",
      "name": "Example Person",
      "mainEntityOfPage": {
        "@id": "https://oneentity.id/p/example-person#webpage"
      }
    }
  ]
}

7. Referencing an Entity-ID

When a website, author profile, imprint, publication or structured data block refers to an entity, the stable Entity @id can be used where a machine-readable identifier is useful.

Public Entity-ID:
https://oneentity.id/p/p7ka-4m2q-x9vz#person

For visible links intended for humans, the resolver URL may be used instead.

Entity-ID:
https://oneentity.id/p/example-person

If the linking page represents the same person or organization, rel="me" may be used where appropriate.

<a href="https://oneentity.id/p/p7ka-4m2q-x9vz#person" rel="me">
  Entity-ID: p7ka-4m2q-x9vz
</a>

8. Sitemaps and discovery

Public records can be discovered through normal HTML links and the oneentity.id sitemap. The sitemap is intended for discovery. Internal links provide site structure and should be followed by crawlers in the usual way.

https://oneentity.id/sitemap.xml
https://oneentity.id/browse

9. Record lifecycle

Public resolution depends on the lifecycle state of a record. Inactive, expired or purged records may stop returning public HTML or JSON-LD. Stable Entity UIDs are not intentionally reassigned to a different entity.

Non-reassignment of an Entity UID does not create a right to perpetual public hosting, indexing, recovery or resolution.

10. Verification status

A public Entity-ID record is an identifier record. Payment, control checks or administrative review do not create a public verification status unless explicitly stated on the record. External identifiers and links are provided as structured references, not as a general endorsement.