---
name: w3ds-reading-existing-data
description: "Use when READING data that already exists in an eVault or across vaults — integrating with a live deployment, discovering what types a vault actually holds, resolving an ontology you did not write, deciding whether a type exists in the ecosystem, or explaining why a record you can see has no name. The base skill covers writing new data; this covers meeting data someone else wrote."
license: Apache 2.0
---

# Reading data you did not write

The base skill's rule — *resolve the `schemaId` from the Ontology service, never invent one* — is correct for **writing**. Applied to **reading** it produces a specific, confident, wrong answer: "there is no ontology for that, so the ecosystem has no such type."

The registry is not the vocabulary. It is the narrowest of several circles.

## The registry is what got merged, not what exists

Measured 2026-09-09, the same deployment on the same day:

| Circle | Count |
|---|---|
| Schemas served by `https://ontology.w3ds.metastate.foundation/schemas` | **42** |
| Schema files in `services/ontology/schemas` on `main` | **64** |
| Distinct types a self-learning reader had catalogued from live vaults | **150** |
| Distinct ontology ids actually carried by envelopes in the live graph | **136** |

112 of the 150 were known-but-unregistered, and not in the long tail — among them types with thousands of carriers: `FileContext`, `Summary`, `DraftMessage`, `AgriculturalField`, `Reminder`, `CallSession`, `Relation`, `AuditEvent`, `DocumentSignature`, `Organization`.

**Never answer "we have no ontology for X" from the registry alone.** Look, in order: the registry; then the self-descriptions of the platforms in `GET https://registry.w3ds.metastate.foundation/platforms`; then the envelopes actually present on the vaults you can read. Report which circles you checked.

### Merged is not deployed

A merged PR registers a schema **in the repository**. The running service serves it only after a deploy, and the two drift. Measured 2026-09-09: 64 files in `main`, 42 served, and `GET /schemas/256510c7-…` (`signingEnvelope`, merged 2026-09-08) answering **404**. Twenty-three schemas were merged and undeployed, including `callSession`, `draftMessage`, `fieldBoundary`, `fieldClaim`, `fieldLink`, `logicalField`, `mediaAsset`, `observation`, `relation`, `preferredHandlers`.

Consequence for a reader: a `schemaId` that 404s on the Ontology service is not evidence the type is fictional. Check the repo and the live data before saying so.

### Unregistered ids work silently

eVault accepts an envelope under an unregistered `schemaId`. Nothing breaks locally; the type is simply unresolvable to every other application. So a working local integration proves nothing about registration, and a registration gap must be **checked, never assumed**.

### A registered schema is not a validator

Registration constrains nothing at write time. Do not treat a registered JSON Schema as a guarantee about data you read, or as protection for data you write. Read live records and follow those.

### Registered schemas are flat

Fields sit at the **top level** of the schema document — there is no outer wrapper property. Assuming a wrapper yields an empty field list for every schema, which reads like "the registry is broken."

## A label does not identify a type

Measured 2026-09-09. `AccessGrant` exists under **three** ids (`15d24c04…` registered, plus `c7e4f2a1…` and `63d0e376…`). `Task` under three. `Signature`, `Note`, `Device`, `SoilSample`, `Reference` under two each. And the reverse: one id can carry two names — `b1d0a8c3-…` is *Binding Document* in the registry and *IdentityClaim* in a platform's self-description.

**Always resolve by id.** When choosing an existing type to reuse, compare the **fields** across every id sharing the label — the ids are usually not interchangeable. Example measured the same day: the registry's `Signature` (`b2c3d4e5…`) is file-scoped (`fileId` + `md5Hash`) and is the *weakest* of three signature types; `DocumentSignature` (`ede4c610…`, 1672 carriers) and `SigningEnvelope` (`256510c7…`) carry organisational authority, and neither is registered.

## Before inventing a type, look for the one that already exists

Three cases where an obvious-looking gap was already filled, each measured:

- **"There is no signature with organisational authority."** `SigningEnvelope` has `authorityRole`, `onBehalfOfEName`, `authorityManifestId`, `keyCustody`, `signingOrder`, `plaintextSha256`. Unregistered.
- **"There is no audit trail."** `AuditEvent` (`8c2c245e…`, 1740 carriers): `action`, `actorEName`, `subjectEName`, `envelopeId`, `occurredAt`, `isAttested`. Unregistered.
- **"AccessGrant forbids delegation, so delegation is impossible."** That is a statement about one schema. `VotingProxy` (`66fb57fe…`) is delegation of decision authority; `OwnershipClaim` (`f577eb36…`) is a time-bounded role assertion.

The pattern: a limitation found in one registered schema gets generalised into a limitation of the ecosystem. Check the other circles first.

## References and canonicals

There is no cross-tenant discovery (see `access-and-exposure.md`), so a reader can only find what sits in their own tenant. That is why **reference envelopes** exist: the same logical record appears as one canonical envelope on the owner's vault plus a reference in each other participant's tenant pointing at it.

A reference is useless without `canonicalOwnerEName` — a bare reference names a record nobody can reach.

**When counting or listing, collapse references onto the canonical**, or you will report duplicates as distinct objects. Measured 2026-09-15 on `SigningEnvelope`: a direct read of two vaults returned **10 records, of which exactly one was canonical**. The other nine carried a different field set entirely (`canonicalEnvelopeId`, `role`, `order`, `sharedBy`, `sharedAt`) and none of the fields that make the record meaningful (`status`, `participants`, `initiatorSignature`, `signingOrder`).

Corollary for anyone building field-frequency statistics: aggregate rates hide this split. The same measurement reported `status` present at rate 1.0 across 27 contributors, while only one record in ten actually had it.

## A record with no name usually has one, one hop away

`Company` and `Project` envelopes carry **no name field**. They hold `id`, `eName`, and `groupManifestEnvelopeId`; the name lives in a `GroupManifest` on the group's own vault.

A naive label fallback of `labelField → name → title → kind` therefore labelled all 34 companies in one graph with the literal string `Company`. Before concluding a record is unnamed, follow its manifest reference.

And do not paper over the gap. An earlier heuristic filled missing project names with the title of a record that merely *referenced* the project, so 90 nodes carried a plausible sentence that was not their name — the MetaState project appeared as *"The avatar photo is not in sync"*. **A false label is worse than a blank**, because a blank is visibly a blank.

## People are not found by the `User` ontology

`User` is the ontology name for a **profile**, and a person may hold several (different name spellings, different photos, shown to different audiences). Searching for people by that type, or by matching node labels against a name, is the fallback — not the method. Resolve identity first; see `identity` handling in the base skill and the forms trap below.

One physical person is one subject with **one eName** and possibly many profile envelopes. Both identifiers are meaningful; one resolves to the other.

## Checklist for a read integration

- [ ] Every ontology id in the code was resolved from a live source in this session, and unresolved ones are marked as such.
- [ ] No "type X does not exist" claim rests on the registry alone.
- [ ] Types chosen for reuse were compared by **fields**, across every id sharing the label.
- [ ] Listings collapse reference envelopes onto their canonical, and the canonical field set is the one relied on.
- [ ] Missing names were followed one hop (manifest) before being reported missing, and nothing invented a plausible substitute.
- [ ] Field-presence figures distinguish canonical from reference records.