Capsule metadata

Capsule metadata gives applications a portable description of a publication while the on-chain Capsule preserves a hash commitment to that description. The current canonical metadata schema is:

presschain.capsule.metadata.v1

Envelope fields

The V1 metadata model contains:

Field	Purpose
`schema_version`	exact schema identifier
`title`	normalized publication title
`canonical_source_uri`	canonical source location
`cover_media_uri`	optional cover media location
`cover_media_hash`	optional bytes32 hash of cover media
`author_identity_ref`	author identity reference
`outlet_identity_ref`	outlet identity reference
`publication_timestamp`	non-zero publication time
`content_type`	normalized lower-case content type
`language`	normalized lower-case language

Example

{
  "schema_version": "presschain.capsule.metadata.v1",
  "title": "Water records show a decade of change",
  "canonical_source_uri": "https://example.org/investigations/water-records",
  "cover_media_uri": "https://cdn.example.org/water-records/cover.webp",
  "cover_media_hash": "0x0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "author_identity_ref": "presskey:0x8c...21f",
  "outlet_identity_ref": "presschain:outlet:0x4a...99b",
  "publication_timestamp": 1789200000,
  "content_type": "article",
  "language": "en"
}

The abbreviated identity examples illustrate format intent only. Use exact canonical references produced by the active identity and outlet systems.

Canonicalization matters

Hashing JSON without canonicalization is dangerous because insignificant representation differences can change the bytes. The canonical Rust model normalizes required string values, enforces the exact schema version, requires a non-zero publication timestamp, lowercases content type and language, and validates cover_media_hash as bytes32 hex when present. Use the canonical model implementation when generating the metadata hash.

Separate content from metadata

The Capsule carries both a contentHash and a metadataHash. This lets an application verify editorial content independently from its descriptive envelope. For example, changing a cover image URI should not silently imply that the article body changed. A revision policy can make those differences explicit.

Stable URIs

A canonical URI should be durable enough that a future reader has a reasonable chance of resolving it. If your application uses content-addressed storage, preserve the full content address. If it uses HTTPS, avoid temporary signed download URLs as canonical metadata. Temporary delivery URLs can be generated at read time without replacing the stable source URI.

Metadata retrieval UX

When loading a Capsule, the application can show three distinct states:

on-chain metadata hash exists
metadata document is retrievable
retrieved canonical bytes match the on-chain hash

Only the third state establishes both availability and integrity. This layered presentation is especially important for archives, because an unavailable metadata host should not be mistaken for an invalid on-chain Capsule.

Start Here

Build Your First App

Network

Identity & Roles

Capsules

Evidence

Verification

Provenance

PRESS Economy

Bounties

Data Model

API

RPC

PressKey

SDK & Integration

Operations & Security

Reference

Capsule Metadata

Capsule metadata

Envelope fields

Example

Canonicalization matters

Separate content from metadata

Stable URIs

Metadata retrieval UX

​Capsule metadata

​Envelope fields

​Example

​Canonicalization matters

​Separate content from metadata

​Stable URIs

​Metadata retrieval UX

Capsule metadata

Envelope fields

Example

Canonicalization matters

Separate content from metadata

Stable URIs

Metadata retrieval UX