identity-canon/canon/CanonicalGlossary.md

# Canonical Glossary

Status: draft. Updated after IDENTITY-WP-0003 corpus backfill and scenario
review. Definitions remain candidate canon terms until human review promotes
them.

## Actor

An entity that can participate in relationships, hold or control accounts, be
represented by another actor, or be projected into downstream systems.

Includes: natural persons, organizations, communities, families, service
accounts, bots, and AI agents.

Excludes: raw identifiers, credentials, claims, and profiles unless they are
being represented as records about an actor.

## Natural Person

A human being. A natural person may have many accounts, profiles, identifiers,
credentials, personas, and relationships.

Excludes: account records, social profiles, legal entities, and artificial
agents.

## Artificial Agent

A non-human actor that performs actions under software, automation, or delegated
control.

Includes: bots, service agents, workloads, and AI agents.

## Collective Actor

An actor composed of or associated with multiple actors.

Includes: organizations, communities, families, households, groups, and teams
when they can participate in relationships or be represented.

## Account

An operational record in a scope that enables access, login, administration, or
system participation.

Includes: human login accounts and service accounts.

Excludes: natural persons, billing accounts, profiles, credentials, and
authorization principals unless a source uses account in that narrower context.

## Service Account

An account intended for software, workload, bot, or automation access rather
than ordinary human interactive use.

## Identity Record

A record that describes, binds, or organizes information about an actor within
a source or scope.

Identity Record is deliberately narrower than bare `identity`; it is a record,
not selfhood, not proof material, and not necessarily a login account.

## Identifier

A value or reference used to distinguish or refer to something within a scope.

Examples: username, email address, LDAP DN, OIDC subject, SAML NameID, DID,
employee number, external source ID.

## Registry Identifier

An **Identifier** issued under a registered organization-identification scheme
with a known issuing authority, jurisdiction, and (when applicable) renewal
lifecycle.

Examples: LEI (ISO 17442 / ICD 0199), national company registration number,
SAM.gov UEI, VAT number, ALEI (ISO 8000-116).

Recommended fields: `scheme` (ICD or scheme URI), `authority`, `authority_class`
(`government_registry`, `regulatory_global`, `commercial_proxy`, `tax`,
`industry_association`), `jurisdiction`, `value`, optional `organization_part_id`
(ISO 6523 OPI for branches), `renewal_required`, `lifecycle_state`, `evidence_source`.

Registry records (GLEIF entry, D&B profile, SAM registration) map to
**Commercial Record** or **Identity Record**, not to the identifier itself.
Link multiple Registry Identifiers for the same entity via **Synonymity
Assertion** when evidenced.

## Proxy Commercial Identifier

A **Registry Identifier** with `authority_class: commercial_proxy` — issued by a
vendor-operated registry that does not create legal entities.

Examples: DUNS (D&B, ICD 0060). Used for credit, procurement, and trade
verification. Distinct from government **ALEI** or incorporating-register IDs.

## Scoped Identifier

An identifier whose meaning is intentionally limited to a relying party,
sector, tenant, realm, application, namespace, or other scope.

## Credential

Evidence or secret material used to prove control, entitlement, or a claim.

Examples: password, passkey, certificate, hardware token, verifiable
credential, qualified electronic seal (`credential_type: qualified_seal`),
recovery code, signed assertion.

Excludes: payment card PAN, CVV, track data, and other PCI cardholder data —
those stay in payment-provider or PCI-scoped downstream vaults. Excludes
tokenized payment method references (`pm_xxx`); use **Payment Instrument
Reference** and **Payment Mandate** instead.

## Claim

A statement made by an issuer or source about an actor, account, identifier,
relationship, or attribute.

## Authenticated Subject

The protocol-level representation of an entity after an issuer or identity
provider identifies it for a relying party.

Examples: OIDC subject, SAML subject.

## Authorization Principal

The entity considered by an authorization system when evaluating whether an
action is allowed.

## Profile

A presentation or attribute surface for an actor or account in a scope.

Examples: public social profile, local application profile, directory profile.

## Persona

A deliberate contextual presentation of an actor, often used to separate roles,
audiences, privacy boundaries, or pseudonymous participation.

## Scope

A boundary within which identifiers, meanings, relationships, accounts,
policies, or lifecycle states are valid.

Examples: tenant, realm, relying party, namespace, application, community,
authorization domain.

## Tenant

An administrative or isolation scope for a system, service, platform, or
application.

A tenant may be associated with an organization, customer, vendor, or community,
but it is not automatically identical to any of them.

## Realm

An issuer, security, or administrative namespace used by an identity system.

After Keycloak and federation source review, Realm remains a **Scope
specialization** for hard identity/admin boundaries (separate user namespaces,
credentials, clients, IdPs). It is not interchangeable with Tenant or
Organization.

## Organization

A collective actor with operational, social, administrative, or structural
continuity.

Excludes: tenant, customer, and legal entity unless those meanings are modeled
as separate relationships or specializations.

## Legal Entity

An organization or other actor recognized by a legal system.

## Legal Person

A person recognized by law as holder of rights and duties. Includes **Natural
Person** and juridical persons (**Organization** / **Legal Entity**).

Use Legal Person when law, registries, or qualified trust services (eIDAS seals,
LEI) treat the party as a liability-bearing subject. Use Natural Person or
Organization when the distinction matters for modeling.

## Beneficial Owner

A natural person who ultimately owns or controls a legal entity customer in
regulated commercial contexts (KYC/AML, FATF R24).

Beneficial Owner is a **role label** for the person, not a participation root.
Model the regulatory linkage with **Beneficial Ownership Relationship** from
the Natural Person to the Organization or Legal Entity customer. Attach
**Evidence Source** from CDD/EDD onboarding, BOI filing, or transparency registry
extract. Distinct from corporate parent **Ownership Relationship** (LEI Level 2)
and from **Representation Relationship** (authorized signers).

## Beneficial Ownership Relationship

A regulated relationship asserting that a **Natural Person** is a beneficial
owner of a **Legal Entity** or **Organization** customer under a stated
jurisdictional scope (e.g., US FinCEN CDD, EU AMLD, FATF R24).

Recommended metadata:

- `ownership_prong` — meets equity threshold (e.g., 25%+).
- `control_prong` — meets substantial control/management test.
- `equity_percentage` — when ownership prong applies.
- `control_basis` — `senior_managing_official`, `chief_executive`, `chief_financial`,
  `managing_member`, `general_partner`, `board_chair`, `trustee`, `settlor_with_control`,
  or `other_control` (with detail text).
- `intermediary_chain` — trust or entity look-through when required.
- `regulatory_basis` — CDD Rule, national statute, or registry filing type.
- `scope`, `evidence_reference`, `lifecycle_state`.

Do not model as an Ownership subtype. Operational ownership (records, tenants,
resources, corporate parents) uses **Ownership Relationship** separately.

## Beneficial Ownership Exemption

**Evidence Source** recording that a Legal Entity or Organization customer is
**exempt** from beneficial ownership collection under a stated rule (e.g.,
publicly traded, government entity, regulated financial institution).

Use explicit exemption Evidence instead of inferring from absent BO relationships.
Carries `exemption_type`, `regulatory_basis`, and `lifecycle_state`.

## Customer

A commercial role played by an actor (usually an Organization, sometimes a
Natural Person for individual subscriptions) that consumes services from a
vendor.

Customer is a relationship role, not a record type and not interchangeable with
Tenant, Organization, Account, or Commercial Record.

## Vendor

A commercial role played by an actor (usually an Organization) that provides
services to customer actors.

Vendor is a relationship role, not a tenant, realm, or organization synonym.

## Commercial Relationship

A typed relationship connecting a vendor actor to a customer actor for a
commercial or subscription purpose within a stated scope.

May reference a Commercial Record for billing state. Does not imply membership,
authorization, or identity equivalence.

## Commercial Commitment

An evidenced obligation that binds commercial parties and raises the cost of
identity fluidity for counterparties.

Examples: signed contract, active subscription, payment mandate, regulated
onboarding acceptance, qualified electronic seal on an agreement, executed
purchase order.

Commercial Commitment carries lifecycle state (proposed, active, breached,
fulfilled, expired, revoked) and may attach to Commercial Relationship,
Commercial Record, or Legal Entity/Organization actors.

Recommended `commitment_type`: `contract` | `subscription` | `payment_mandate` |
`purchase_order` | `escrow` | `regulatory_onboarding` | `amendment` | other.

`binding_trigger` on promotion from **Pipeline Pursuit**: `quote_accepted`,
`loi_signed`, `purchase_order_executed`, `contract_executed`, `subscription_activated`,
`regulatory_onboarding_complete`, `org_policy_closed_won` (downstream policy
Evidence required).

Does not include CRM pipeline stages by default — see **Pipeline Pursuit**.
Salesforce Forecast "Commit" category is sales confidence, not this concept.

## Payment Instrument Reference

A **Scoped Identifier** for a tokenized payment instrument in a payment-provider
scope — not PAN, not a login **Credential**.

Examples: Stripe `pm_xxx`, SEPA mandate reference, network token ID, display
last4 + fingerprint.

Links to **Commercial Record**. Carries `provider_scope`, `instrument_type`,
`reusable`, and `lifecycle_state` (attached, detached, revoked). CHD stays
downstream; canon holds references only.

## Payment Mandate

A **Commercial Commitment** (`commitment_type: payment_mandate`) authorizing
future charges against a **Payment Instrument Reference**.

Created when customer consent is evidenced (SetupIntent success, signed debit
mandate, card-on-file with off-session authorization). Distinct from
**subscription** commitment but often co-created at checkout. Assurance tier:
committed.

## Pipeline Pursuit

A Record layer artifact for an in-flight sales or procurement deal before a
binding **Commercial Commitment** exists.

Examples: Salesforce Opportunity, HubSpot deal, renewal pursuit on existing
account.

Carries `stage`, `forecast_category`, `pursuit_role` (`customer`, `partner`,
`vendor`), expected amount/date, and `lifecycle_state` (open, won, lost).
Stage changes are **Evidence Source** (internal telemetry); they do not alone
create Commercial Commitment. Promote only on `binding_trigger`. Renewals on an
existing contract use **commitment amendment** on the prior Commercial Commitment
(optional Pipeline Pursuit for forecast); competitive rebids use new Pipeline Pursuit.

## Commercial Record

A record in a billing, CRM, or commerce system that tracks payment methods,
subscriptions, invoices, contracts, or commercial contact details for an actor
or tenant.

Examples: Stripe Customer, Salesforce Account, subscription billing profile.

Commercial Record is in the Record layer. It is not an Account (login), not an
Organization actor, and not a Customer Account. Link it to Actor, Tenant, or
Scope via Identifier binding or Commercial Relationship.

## Community

A collective actor formed around participation, affiliation, identity, interest,
moderation, or social interaction.

## Family Or Household

A collective actor or relationship network involving family, guardian,
dependent, household, or care relationships.

This concept is privacy-sensitive and may have legal implications outside the
canon's scope.

## Group

A named collection of actors or accounts in a scope.

Group membership may have authorization implications, but a group is not the
same concept as a role, community, team, or organization.

## Role

A named capability bundle, responsibility, or relationship label within a
scope.

Roles may be assigned through memberships or relationships, but role is not
identical to group.

## Relationship

A typed, scoped assertion connecting one actor, account, identifier, group, or
other model element to another.

Recommended fields: source, target, type, scope, evidence, issuer or source,
confidence when relevant, lifecycle state, and authorization implications.

## Membership Relationship

A relationship indicating that an actor or account belongs to, participates in,
or is accepted by a collective actor or scope.

## Affiliation Relationship

A relationship indicating association without necessarily implying membership,
control, employment, or authorization.

## Following Relationship

A directed social relationship where one actor subscribes to, follows, or
observes another actor or profile.

## Representation Relationship

A relationship where one actor acts or speaks on behalf of another actor within
a scope.

## Delegation Relationship

A relationship where one actor grants bounded authority to another actor.

## Administration Relationship

A relationship where one actor has management authority over accounts,
relationships, policies, or configuration in a scope.

## Trust Relationship

A relationship where one actor, issuer, verifier, system, or scope relies on
another for claims, identifiers, credentials, or decisions.

For commercial counterparty reliance, cite an **assurance_basis**: which tier of
the **Counterparty Assurance Gradient** supports the trust (opinion signal,
observed metric, commercial commitment, or adjudication outcome). Do not treat
weak opinion-tier evidence as equivalent to committed or adjudicated assurance.

## Synonymity Assertion

A scoped, evidenced assertion that two or more identifiers, records, accounts,
profiles, or actors refer to the same target for a stated purpose.

Recommended relation types: `same_as`, `probably_same_as`, `linked_to`,
`represents`, `controls`, `acts_for`.

Recommended strength bands: weak, medium, strong, authoritative.

Synonymity assertions may be verified, inferred, revoked, privacy-limited, or
source-specific. They do not require destructive merging of source records.

Common sources: OIDC iss+sub account binding, SAML persistent NameID mapping,
entity-resolution matches, operator verification, VC cryptographic proof,
schema.org sameAs (weak by default).

## Evidence Source

A source, document, event, issuer, import, observation, or verification process
supporting a claim, relationship, or synonymity assertion.

Recommended commercial field: `assurance_tier` — `opinion` | `observed` |
`committed` | `adjudicated` (see **Counterparty Assurance Gradient**).

## Counterparty Assurance Gradient

A four-tier pattern for how counterparties earn reliance, from weak social proof
to enforceable outcomes. Higher tiers do not erase lower tiers but constrain how
much weight lower tiers may carry.

| Tier | Label | Examples | Canon anchor |
| --- | --- | --- | --- |
| 1 | Opinion | Star ratings, reviews, karma, badges | Reputation Signal |
| 2 | Observed | PAYDEX, SLA stats, chargeback rate, KYC pass | Performance Evidence |
| 3 | Committed | Contract, bond, escrow, SLA penalties, payment mandate | Commercial Commitment |
| 4 | Adjudicated | Arbitration award, court judgment, regulator enforcement | Adjudication Outcome |

Identity attribution strengthens up the gradient: opinion may attach to Persona
or platform Profile; adjudication attaches to Legal Entity with Registry Identifier.

## Reputation Signal

An **Evidence Source** with `assurance_tier: opinion` — crowd-sourced or
platform-computed social proof attributed to an actor, profile, or commercial record.

Examples: star ratings, customer reviews, marketplace feedback scores, community karma.

Default trust strength: weak. Subject to gaming (fake reviews, Sybil accounts,
review bombing). Scope-local to the issuing platform unless portable via explicit
Synonymity Assertion. Not a **Commercial Commitment** and not interchangeable with
credit metrics or legal outcomes.

## Performance Evidence

An **Evidence Source** with `assurance_tier: observed` — metrics or attestations
grounded in observable transactions, registry facts, or third-party measurement.

Examples: PAYDEX, business credit score, on-time delivery rate, chargeback ratio,
sanctions-screen result, LEI renewal status.

Usually links to **Commercial Record**, **Organization**, or **Registry Identifier**.
Supports medium-to-strong **Trust Relationship** when issuer is authoritative.

## Adjudication Outcome

An **Evidence Source** with `assurance_tier: adjudicated` — formal dispute or
enforcement result from arbitration, courts, regulators, or binding platform
resolution processes.

Examples: arbitration award, court judgment, regulatory consent order, binding
chargeback ruling, bankruptcy filing.

May trigger **Commercial Commitment** lifecycle change (breached, fulfilled) and
**Trust Relationship** revocation. Attaches to **Legal Entity** / **Organization**
actors, not merely to profiles or opinion aggregates.

## Non-Canonical Convenience Term: Reputation

`Reputation` is overloaded (reviews, credit, brand, legal standing). Do not use
as a canonical root. Resolve to **Counterparty Assurance Gradient** tier and the
specific Evidence Source or Commercial Commitment before modeling.

## Lifecycle State

The current state of a record, account, relationship, credential, claim, or
assertion.

Examples: proposed, active, suspended, revoked, expired, archived, deleted,
superseded.

Security event streams (SSF/CAEP/RISC) and VC status mechanisms are common
Evidence Sources that trigger lifecycle transitions.

## Assurance Level

Confidence metadata about identity proofing, authentication, or federation
derived from sources such as NIST SP 800-63-4.

Dimensions:

- Identity Assurance Level (IAL): confidence that a subscriber is the claimed person.
- Authenticator Assurance Level (AAL): confidence in authentication mechanism.
- Federation Assurance Level (FAL): confidence in federation assertion protection.

Assurance levels attach to bindings, credentials, and federation relationships;
they do not replace authorization decisions.

## Relationship Tuple

An authorization projection encoding a subject-relation-object fact in engines
such as Zanzibar, OpenFGA, or Ory Keto.

Relationship tuples are not canonical identity roots. They project from actors,
accounts, memberships, and delegations into authorization domains.

## Pseudonymous Identifier

An identifier designed to limit cross-scope correlation, aligned with privacy
patterns such as OIDC pairwise subjects, tenant-local subjects, and GDPR
pseudonymization with separately stored re-identification keys.

## Non-Canonical Convenience Term: User

`User` may be used in prose when quoting or mapping external systems, but it
should not be a canonical root concept. Resolve it to a specific canonical
concept before using it in model definitions.

## Non-Canonical Convenience Term: Subscriber

`Subscriber` (common in Auth0 B2B SaaS documentation) usually means the
organization or party holding a subscription and tenant. Resolve to Organization
+ Customer Relationship role + Tenant Scope, or to Natural Person + Tenant for
individual subscriptions. Do not model as Customer Account or Account.

## Non-Canonical Convenience Term: Customer Account

Do not use `Customer Account` as a canonical term. Resolve by layer:

- login/access → Account;
- subscribing company → Organization + Customer Relationship role;
- billing/CRM record → Commercial Record;
- isolation boundary → Tenant.