Entity projection

A verification response can include a rich entity graph: multiple identifiers, registrations, names, addresses, status records, and a timeline of events, linked together via ephemeral keys.

That richness is intentional. It preserves evidence and traceability, but it is not always the shape you want to store, display, or feed into decision logic.

Entity projection is the step where you derive a resolved snapshot from that graph.

What projection solves

Projection exists because a verification result often contains:

• multiple candidate values for the same concept (several names, several addresses)
• relationships expressed as keys (e.g. a registration refers to one or more identifier keys)
• facts that are valid only for a specific period (names, addresses, statuses)
• timeline events that provide context and ordering

The SDK entity helpers are designed to:

1. resolve internal references into direct objects
2. apply deterministic selection rules where multiple candidates exist
3. return a coherent snapshot based on time filters or other criteria

Entity projection operates on verification results, it never queries registries directly. This means that projection can only select from data already returned by the engine.

For verification semantics and response structure, see Verify an ID and Verify and decide.

Projecting the current entity

1
import { createVerifyVatClient, Verifier, Entity } from '@verifyvat/sdk'
2

3
const client = createVerifyVatClient()
4
const verifier = new Verifier(client)
5

6
const verification = await verifier.verifyId({
7
    type: 'no_orgnr',
8
    id: '914778271',
9
})
10

11
if (verification.entity) {
12
    const entity = new Entity(verification.entity)
13
    const card = entity.describe()
14
}

1
from verifyvat_sdk import VerifyVatClient, Verifier, Entity
2

3
client = VerifyVatClient()
4
verifier = Verifier(client)
5

6
verification = verifier.verify_id(
7
    type="no_orgnr",
8
    id="914778271",
9
)
10

11
if verification["entity"]:
12
    entity = Entity(verification["entity"])
13
    card = entity.describe()

The resulting entity is a structured view derived from the verification data. No information is fabricated, and no registry calls are performed.

Time travel and historical projection

Some workflows need historical snapshots, for example audits, compliance checks, or backfilled reconciliation.

The SDK supports projecting the entity as of a specific date using the timeline and validity windows carried by the engine response.

1
// continuing from above
2

3
const asOf2019 = entity.describe({ on: '2019-06-01' })

1
# continuing from above
2

3
as_of_2019 = entity.describe(on="2019-06-01")

Time travel yields a coherent historical snapshot:

• names, addresses, and statuses are filtered by validity
• timeline events are applied in order
• the result represents a stable state at the chosen date, not a partial diff

What projection does

Projection applies a set of selection rules over the raw entity data.

Some of the rules applied include:

• preferring legal names over trading names
• favouring recent records over historical ones
• resolving references between registrations and identifiers

These rules are deterministic and traceable. The raw data remains available if you need full fidelity.

Customising projection behaviour

Selection is opinionated by default, but it is not a black box. The goal is consistency and auditability. The SDK exposes the underlying machinery so policies can be steered, you can:

• prioritise different name kinds
• change which registrations types are preferred
• alter recency rules for specific domains
• derive alternative projections for different consumers (storage, UI, decisioning)