Skip to main content

Protocol specification

Identifiers

Network IDs, property IDs, dataset IDs, and the credential ID format.

OLPN uses four kinds of identifiers, all of them strings, all of them intended to be legible to both humans and machines. They do not resolve through DNS on their own; they name things that the resolver then locates by convention (a known path on a known domain).

Entity: §:entity:{domain}

Every entity has a network ID of the form §:entity:{domain}. The § prefix is literal. The entity label distinguishes this from a property or dataset ID. The {domain} is the fully qualified domain where the entity publishes its olpn.json.

Examples:

  • §:entity:nickcarroll.com
  • §:entity:hkgclaw.com
  • §:entity:maine-bar.org

The resolver parses the network ID by splitting at the last colon. The text after the last colon is the domain. The text before is the prefix (§:entity:). Nothing else is permitted in the network ID itself: no paths, no query strings, no fragments.

Property: §:property:{domain}

A property ID has the form §:property:{domain}. Properties name sites or domains an entity owns or controls. The domain in the property ID is the host that will serve the property document at /olpn-property.json.

Examples:

  • §:property:nickcarroll.com
  • §:property:hkgclaw.com
  • §:property:legalexaminer.com

An entity's self-property (the domain where its olpn.json lives) typically has the same domain as its network ID, just with the §:property: prefix instead of §:entity:. They are not the same ID, and the resolver treats them as two separate things.

Dataset: §:dataset:{domain}/{path}

Dataset IDs name a group of credentials issued by a property. The format is §:dataset:{domain}/{path}. The path segment distinguishes multiple datasets under a single issuer.

Examples:

  • §:dataset:olpn.org/founding-supporters
  • §:dataset:hkgclaw.com/attorneys
  • §:dataset:maine-bar.org/active-members

Datasets are a grouping mechanism on the issuer's side. An entity's credential document refers to the dataset it was issued against so consumers can understand the context ("this is a contributor credential, not an employment credential").

Credential: @username@domain[/path]

Credential IDs are the one identifier that does not use the §: prefix. They follow a mail-like pattern: @username@domain[/path]. The leading @ is literal. The portion between the two @ is the issuer-assigned username. The portion after the second @ is the issuer domain, optionally with a path segment encoding a dataset.

Examples:

The resolver parses credential IDs by finding the second @ (so any @ characters after the second one are treated as part of the domain/path, not a separator). Each of username, domain, and path must be non-empty where present. The username is used as the path segment when fetching the credential document:

https://{domain}/{username}/olpn-credential.json

Case sensitivity

All identifiers are compared case-insensitively by the resolver. A claim of §:entity:Example.com and a back-link of §:entity:example.com are considered equal. Implementers should preserve the author's chosen casing when rendering, but never depend on exact-match when comparing.

Stability

An identifier points at a domain. If an entity changes domains, its network ID changes. There is no redirect mechanism in the protocol. An entity that moves hosts should publish the old identity's olpn.json with an HTTP 301 or 308 redirect to the new domain, and request that issuers of credentials update the back-links.

This is a deliberate design choice. The protocol keeps the identifier scheme as simple as possible; identity portability is the host's job (see Integrate OLPN into an existing platform).