> ## Documentation Index
> Fetch the complete documentation index at: https://docs.presschain.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Capsule Metadata

> Build and hash the canonical PressChain Capsule metadata envelope.

# 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:

```text theme={null}
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

```json theme={null}
{
  "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:

1. on-chain metadata hash exists
2. metadata document is retrievable
3. 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.