Skip to main content

Getting started

The three document types, in 60 seconds

Entity, property, and credential documents, and how they link to each other.

Every claim in OLPN is grounded in one of three documents. Each is a JSON file served over HTTPS at a predictable path. The resolver fetches them in combination to verify back-links.

Entity document

Served at {domain}/olpn.json. This is an entity's public record: a profile, a list of properties the entity owns, a list of credentials the entity has been issued, and a list of rel=me connections.

Every OLPN identity starts here. If you are a lawyer, you have one entity document at the domain you own. If you are a firm or a bar association, you have one entity document at your organization's domain. Same shape either way.

Property document

Served at {domain}/olpn-property.json. A property is any domain or site an entity owns or controls. The property document lists which entities claim ownership. When an entity's olpn.json lists a property, the resolver fetches the property document and looks for the entity's ID in the ownership[] array. Both sides must name each other for the claim to verify.

Credential document

Served at {issuer-domain}/{username}/olpn-credential.json. An issuer publishes one credential document per credential it has granted. The document names who the credential was issued to via an olpn_entity_id field. When an entity claims a credential in its olpn.json, the resolver fetches this document and checks the back-link.

The protocol is built on mutual back-links. Each claim is only verified when both documents agree:

  • Property: entity claims §:property:firm.com, and firm.com/olpn-property.json includes §:entity:the-entity in its ownership[].
  • Credential: entity claims credential @[email protected], and bar.example.com/jane/olpn-credential.json sets olpn_entity_id to the entity's network ID.

There is no central registry. Nothing is trusted because a service says so. Trust is computed from two documents fetched independently from whoever claims to hold them.

HTML fallback

Not every host can serve arbitrary JSON at arbitrary paths. Each document has an HTML-embedded equivalent: a <script type="application/json" id="..."> tag in the page body. The resolver checks the JSON URL first and falls back to the HTML embed. See HTML fallback for the full pattern.