Entity document (olpn.json)

The entity document is the root of an OLPN identity. It sits at https://{domain}/olpn.json and declares the entity's network ID, profile details, and the lists of properties, credentials, and connections the entity claims.

Shape

{
  "version": "0.9",
  "last_updated": "2026-04-24T12:00:00Z",
  "entity_type": "person" | "organization",
  "network_id": "§:entity:example.com",
  "details": { ... },
  "properties": [ ... ],
  "credentials": [ ... ],
  "other_connections": [ ... ]
}

Fields

version (string, optional)

Protocol version the document targets. The current published version is 0.9. The resolver does not currently enforce a version check, but implementers should set a recognizable value.

last_updated (ISO-8601 timestamp, optional)

When the document was last changed. Implementations should update this on every change so consumers can detect freshness. Not currently used for cache invalidation by the resolver, but reserved for that purpose.

entity_type (string, required)

One of person or organization. Drives the schema.org JSON-LD the resolver emits for the entity on search results pages: person maps to Person, organization maps to Organization.

network_id (string, required)

The entity's identifier. Must be of the form §:entity:{domain}. The {domain} should be the same domain the document is served from. The resolver will reject a document that has no network_id.

details (object, optional)

Profile metadata. All subfields are optional. Use what applies.

• name (string) — display name.
• domain (string) — primary domain. Usually the same as the domain in network_id.
• email (string) — public contact email.
• location (string) — human-readable location.
• legal_name (string) — formal legal name (most useful for organizations).
• established (string) — year or date the entity was established. Organizations only.
• registered_in (string) — jurisdiction of legal registration.
• legal_entity_type (string) — LLC, PLLC, C Corporation, Nonprofit, etc.
• description (string) — free-form description, typically one or two sentences.

properties (array, optional)

Each entry is a Property object. See Property document for the full shape. At minimum an entry should include id, url, and an ownership[] array naming the entity.

credentials (array, optional)

Each entry is a Credential object. See Credential document for the full shape. At minimum an entry should include id (the credential ID), title, type, and a nested property object describing the issuer.

other_connections (array, optional)

Each entry is a Connection object with a single id field containing a URL. Intended for rel=me verification against ActivityPub profiles, GitHub pages, and similar identity attestations. Currently minimally implemented by the resolver.

Minimum viable document

{
  "network_id": "§:entity:example.com"
}

This is legal. The resolver will parse it and return the entity with no profile details, no properties, and no credentials. Useful for a brand-new identity before anything has been anchored to it.

Serving rules

• Path: must be exactly /olpn.json at the entity's domain.
• Content-Type: application/json recommended. The resolver will warn on other types but still attempt to parse.
• HTTP status: 200. Anything else is treated as not found.
• CORS: no specific requirement. Server-to-server fetches only.
• Caching: entity documents can be cached aggressively. No public cache-busting mechanism is defined; consumers assume up to a day of staleness is acceptable.

Validation

The resolver validates:

1. JSON parses.
2. The document has a non-empty network_id field.
3. The network_id matches the §:entity:{domain} shape (prefix before last colon, domain after).

Property and credential entries are validated independently during verification. A malformed entry does not invalidate the rest of the document.