Standardize automatic metadata handling for attachments

Proposal

Standardize one convention for how upload adapters automatically extract, publish, and expose optional detailed metadata associated with Hypercerts attachments. Our proposed starting point is a second attachment containing versioned metadata JSON, linked to the original media attachment through subjects.

This is an implementation convention chosen once by application developers. Users should not choose between a metadata record and a metadata attachment on each upload.

Relationship to the existing PRs

• #251 adds optional attachment tags using the existing collection/feature classification structure.
• #252 proposes optional capturedAt, separate from createdAt, with explicit instant, local-date-time, and calendar-date variants.

This discussion complements those contributions and does not block either PR. Extracting a capture date does not require publishing a separate metadata record or file. The main attachment can carry capturedAt directly; the optional metadata layer preserves supporting details and their source.

Proposed automatic adapter behavior

1. Extract supported metadata from uploaded media, preserving the original values needed to interpret it.
2. Populate capturedAt when capture time is known, preserving date-only precision or unknown timezone. If unknown, omit it. Set createdAt independently to record-creation time; never copy upload time into an unknown capture time.
3. When additional supported metadata is present and permitted for publication, publish it automatically in the agreed versioned JSON format, carried by a second attachment. Link that attachment to the original through a strong reference in subjects, and identify the specific media asset when there are multiple renditions.
4. When no additional metadata is available or permitted, omit the supporting attachment. Media upload should still succeed. Optional metadata processing/publication should be retryable without duplicating the main attachment.
5. Preserve provenance distinctions, including extracted versus user-supplied values. Supporting metadata should explain the publisher-declared capture time, not create a competing authoritative date.

Publication rules must filter sensitive metadata before publication, including metadata embedded in media bytes. A separate attachment is not a privacy boundary.

Proposed reader and indexer behavior

• Recognize metadata attachments through an agreed content-type/profile identifier and validate their JSON against a versioned specification. These identifiers and the payload format still need agreement; we are not claiming an existing standard here.
• Index the metadata-to-media relationship, retaining the referenced attachment version and asset identity. Provide a lookup and a combined observation view so clients do not need to fetch metadata JSON on every hover.
• Keep supporting metadata attachments out of ordinary galleries, map pins, and capture timelines. Display one media observation, with metadata available in its details/provenance view.
• Missing or unreadable optional metadata must not hide otherwise usable media. Media without coordinates stays in the gallery; unknown capture dates remain visibly unknown. A UI may show an explicitly labelled “Added on” date without treating it as capture time.
• Define how publisher-endorsed metadata is selected, how corrections are versioned, and how third-party or conflicting metadata is distinguished. A link alone does not establish endorsement or verification.

Camera GPS must not automatically be interpreted as the location of the photographed subject. The convention should distinguish those meanings when retaining location metadata.

Why a second attachment?

The existing attachment schema already permits external files/blobs and attachment-to-attachment subjects references. A small shared profile can use those capabilities without immediately introducing another record lexicon. It still requires a defined JSON schema, validation, discovery, and correction rules; arbitrary JSON alone is not interoperability.

A dedicated metadata lexicon is the alternative worth comparing. It would offer generated types and directly indexable record fields, at the cost of another schema to maintain and adopt. The second-attachment approach requires an extra payload retrieval for indexing. Both options require consistent linking, versioning, and reader behavior.

Eve's Grain EXIF example is a useful precedent for separating detailed metadata from media. Reuse or adaptation should be assessed rather than assuming Grain's photo-specific record is already a shared Hypercerts metadata contract.

Feedback requested

1. Does the second-attachment approach meet initial interoperability needs, or is there an existing reusable metadata lexicon or concrete consumer requirement that makes a dedicated record preferable now?
2. What minimal versioned payload and content-type/profile identifier should adapters support for photos and videos, including metadata source and asset identity?
3. What reference, author-selection, and correction rules should indexers implement consistently?

The desired outcome is one documented adapter-and-reader contract, with shared fixtures, that implementations can follow automatically. This issue does not propose new verification flags, mandatory metadata for every upload, or changes to the chosen capture-time representation in #252.

Start with the existing attachment schema and the related proposals in #251 and #252, then compare the second-attachment approach with the linked Grain EXIF example. Done means resolving the open questions into one versioned adapter/reader contract covering payload and profile identifiers, linking and correction rules, privacy filtering, and shared fixtures.