λORE

Each entry inside resources represents one digital resource.

locators MUST be a JSON array containing at least one Locator object. An empty array is invalid. A resource MUST NOT contain two locators with the same (protocol, id) pair.

The array is preference-ordered: the first entry is the emitter's preferred locator. Position is the only ordering channel; there is no priority or weight field.

All locators in a resource whose protocol is classified retrievable MUST address byte-identical content. A copy that differs in any byte - a transcode, a re-scan, a thumbnail, a recompression - is a different resource, not another locator for this one.

Locator

protocol MUST be a non-empty lowercase ASCII string matching ^[a-z][a-z0-9+.-]*$. It MUST NOT contain ://, a scheme, or a path separator.

id MUST be a non-empty string, in exactly the form the registry defines for that protocol. It MUST NOT repeat the protocol token as a prefix and MUST NOT carry a foreign namespace prefix. {"protocol":"ipfs","id":"ipfs://bafy..."} and {"protocol":"ipfs","id":"ia:Free_as_in_Freedom"} are both invalid; the second is exactly the protocol/identifier mixing this revision removes.

id names what, never where from. A locator MUST NOT carry a gateway, host, node, or endpoint, and a decoder MUST NOT take a retrieval endpoint from a LORE document. Gateway and node selection is decoder configuration.

Two locators in one resource MAY share a protocol. Order then decides preference.

Unknown fields inside a Locator MUST be ignored, per the Compatibility rules.

Identifiers in the examples throughout this document are elided: an ellipsis stands for the omitted remainder of a real identifier, as in bafy... or zDvZRwzm.... They illustrate the shape of a locator and are not resolvable. A conforming document carries the identifier in full.

The registry is the sole authority for the protocol namespace. It contains exactly one token per protocol; aliases MUST NOT be registered.

The class column tells a decoder what a locator is for. retrievable means "the resource's exact bytes are obtainable here". provenance means "this is where the resource came from"; it is an origin statement, not a retrieval target.

logosRetrievablecontent-addressed

id syntaxBare Logos Storage manifest CID: CIDv1, multibase base58btc, multicodec storage-manifest (0xCD01), multihash sha2-256. Always exactly 52 characters beginning zDvZRwz. No scheme, no host, no gateway, and no <cid>/<path> suffix - a manifest addresses exactly one file, not a directory. Block CIDs (0xCD02, prefix zDxWB8E) and dataset-root CIDs (0xCD03, prefix zDzSvJT) are internal to the protocol and MUST NOT appear as a locator id.

ResolutionRequest the id from a Logos Storage node the decoder is configured with: GET <node>/api/storage/v1/data/<id>/network/stream. Nodes predating the Codex-to-Logos-Storage rename serve the same route under /api/codex/v1.

ipfsRetrievablecontent-addressed

id syntaxBare CID. CIDv1 lowercase base32 RECOMMENDED. MAY be <cid>/<path> to address a file inside a directory CID. MUST NOT include ipfs://, /ipfs/, or a gateway host.

ResolutionFetch the CID from an IPFS node or gateway the decoder is configured with.

arweaveRetrievablecontent-addressed

id syntaxBare 43-character base64url transaction id. No scheme, no host.

ResolutionGET the transaction id from an Arweave gateway the decoder is configured with.

iaProvenance

id syntax<item>, or <item>/<file>, where <item> is the Internet Archive item identifier and <file> is a path within the item. MUST NOT carry an ia: prefix - the prefix is the protocol token.

ResolutionHuman-facing reference: https://archive.org/details/<item>. Item metadata: https://archive.org/metadata/<item>. See the note below for when bytes MAY be fetched.

logos is content-addressed and self-verifying, and SHOULD be listed first when present. Emitters SHOULD include at least one content-addressed retrievable locator in every resource.

A logos id is self-verifying in one direction only: the bytes retrieved under it are cryptographically bound to it, so identical ids imply identical bytes. It is not a pure function of those bytes. The manifest also commits to the upload's block size, filename and MIME type, so byte-identical content uploaded with different parameters yields a different id. Emitters MUST record the id the node returned and MUST NOT attempt to recompute it from the bytes; decoders MUST NOT treat two differing logos ids as evidence that the content differs.

The storage-manifest, storage-block and storage-root multicodecs are private-use values and are not registered in the multiformats table. Generic CID tooling will parse a logos id structurally but will not recognise its codec, and no IPFS gateway will resolve one.

Why ia is provenance, not retrievable

archive.org does serve bytes; the classification is a deliberate policy, not a statement about capability. An Internet Archive identifier addresses a mutable, multi-file item whose contents can change, so it does not commit to a specific byte string the way a CID does.

A decoder MUST NOT use an ia locator to satisfy retrieval automatically. A decoder MAY, only in response to an explicit user action, fetch https://archive.org/download/<item>/<file> from an ia locator whose id carries a <file> segment. If it does, and the resource carries a checksum attribute, it MUST verify the bytes against it and discard them on mismatch; if the resource carries no checksum, the decoder MUST present the bytes as unverified origin content and MUST NOT present them as the resource's pinned content or cache them as such.

The Internet Archive token is ia

internet_archive is not a registered protocol token and MUST NOT appear as a protocol value. It remains a legal free-form value of a source attribute - but attributes are display metadata, and a decoder MUST NOT read source, identifier, external_url, or any other attribute to resolve or classify a resource.

Once a resource carries an ia locator, source and identifier attributes restating it are redundant and SHOULD be omitted; the locator is the normative machine-readable statement of origin.

Unregistered protocols

LORE is storage-agnostic, so unregistered tokens are PERMITTED. An unregistered token has no class. A decoder MUST treat it as retained and inert: it MUST NOT attempt retrieval, MUST NOT reject the locator, the resource, or the document, MUST retain protocol and id verbatim, and MAY display them as an opaque reference. A decoder MUST NOT guess a resolution rule from the token's spelling and MUST NOT fall back to treating id as a URL. A decoder MAY resolve unregistered tokens through a private, out-of-band registry; a closed ecosystem knows its own protocols.

Experimental tokens SHOULD be prefixed x- (for example x-keeper-cache) so they cannot squat a name the registry may later assign. This is a naming convention; it adds no schema.

Registry additions are made by pull request against this document, one row per protocol. A registry addition is not a wire-format change and MUST NOT increment version.

Given a resource R with locators L[0] through L[n-1]:

1. Order. A decoder MUST attempt retrieval in array order, beginning at L[0].

2. Candidate selection. For each L[i], the decoder MUST look up L[i].protocol in the Protocol Registry, then:

• If the token is not registered, skip L[i] for retrieval.
• If the token is registered with class provenance, skip L[i] for retrieval.
• If the token is registered with class retrievable but the decoder implements no resolver for it, skip L[i] for retrieval.
• Otherwise the decoder MUST attempt to obtain the bytes using the registry's documented resolution rule for that token. It MUST NOT substitute a resolution rule of its own devising.

3. Verification. On a successful fetch:

• If the protocol is content-addressed, the decoder MUST verify the returned bytes against id itself. It MUST NOT accept a node's or gateway's assertion that the content address matched.
• Verifying against a content address is protocol-specific, and is not always a hash of the retrieved bytes. For logos the id commits to the dataset manifest, not to the content: a decoder MUST confirm that sha2-256 of the manifest block equals the digest carried in id, then re-chunk the retrieved bytes at the manifest's block size, rebuild the merkle tree over the block hashes, and confirm the root equals the manifest's tree CID and the total length equals its dataset size. A decoder that cannot perform a protocol's check MUST treat the locator as unresolvable rather than accept the node's assertion.
• If R carries a checksum attribute, the decoder MUST verify the returned bytes against it.
• On any verification failure the decoder MUST discard the bytes, MUST NOT present or cache them, SHOULD report the failing locator, and MUST continue at step 2 with L[i+1].
• If R carries no checksum and the protocol is not content-addressed, the bytes are unverified: the decoder MAY present them and SHOULD mark them unverified.

4. Success. The result is the earliest-ordered locator that yields verified bytes; the decoder MUST NOT present a later locator's bytes when an earlier locator succeeded. A decoder MAY fetch candidates in parallel and MAY serve from a local cache regardless of order, provided the bytes it presents are the bytes the earliest successful locator would have produced.

5. Failure. If every locator is skipped or fails, retrieval of R fails. The decoder MUST report failure rather than presenting partial or substitute content, and SHOULD report which protocols it skipped for lack of a resolver, so the failure is diagnosable as "unsupported protocol" rather than "resource gone".

6. Provenance.

• A provenance locator MUST NOT satisfy retrieval.
• A decoder SHOULD surface provenance locators as origin information, built from the registry's documented reference form for that token, and MUST distinguish them visually from retrieved content.
• A decoder MUST NOT present a provenance claim as verified. It is an assertion by the publisher.
• A decoder MUST NOT infer provenance from source, identifier, external_url, or any other attribute. Attributes are display metadata; locators is the resolution surface.

7. Emitters.

• Emitters MUST order locators by descending preference.
• Emitters SHOULD place all provenance locators after all retrievable locators.
• Emitters SHOULD include at least one content-addressed retrievable locator.
• Emitters MUST NOT emit duplicate (protocol, id) pairs within one resource.
• A resource whose locators are all provenance is valid - it describes an object that is catalogued but not yet pinned. Retrieval of such a resource fails per step 5, and a decoder SHOULD present it as "origin known, not retrievable" rather than as a malformed document.

8. Independence. Resources are resolved independently, per the Compatibility rules. Failure of one resource MUST NOT abort resolution of the others, and MUST NOT invalidate the document.

LORE adopts the OpenSea metadata format.

{
  "trait_type": "Background",
  "value": "Blue"
}

Attributes may exist at:

• Object level
• Resource level

Object attributes describe the digital object.

Resource attributes describe individual resources.

Recommended resource traits include:

• role
• mime
• size
• width
• height
• duration
• language
• codec
• checksum

Applications may define additional traits.

Attributes are display metadata. A decoder MUST NOT read an attribute to resolve, classify, or locate a resource; that is what locators is for.

The one attribute the Retrieval rules do read is checksum. Its value MUST be <algorithm>:<lowercase-hex-digest>, and sha256 is the only algorithm registered in this revision - for example {"trait_type":"checksum","value":"sha256:4f9a..."}. A resource SHOULD NOT carry more than one checksum attribute; a decoder that finds more than one MUST NOT use any of them for verification and MUST treat the resource as carrying no checksum.

A LORE parser MUST:

• Validate standard == "LORE".
• Validate the supported version.
• Parse every resource independently.
• Treat locators as an array of one or more Locator objects. There is exactly one accepted shape; a decoder MUST NOT accept a bare object or a bare string in this field.
• Ignore unknown attributes.
• Ignore unknown future fields.

This ensures forward compatibility.

An earlier circulated draft of this document carried a singular locator (object) in place of locators (array). It was replaced before any implementation existed. locator is not a recognised field and it is not an alias. No special handling is required: locators is required, so a document carrying only locator is missing a required field and is invalid under the existing rules. Validators SHOULD emit the specific diagnostic locator: renamed to locators (array) rather than a generic unknown-field warning, so that copy-paste from the earlier draft fails loudly.

The version integer identifies the wire format. It counts breaking changes made after a format has at least one implementation, and LORE has none yet. Adding a row to the Protocol Registry, adding a recommended trait, or adding an optional field MUST NOT increment version - those are absorbed by the ignore-unknown rules. The v0.x label on this document identifies the specification document edition and is independent of the version integer; do not couple them.

This specification is released into the public domain for unrestricted implementation.