Skip to main content

Attribute Definition Model

Summary​

An attribute definition is the governed schema for an attribute. It separates immutable record identity, semantic naming, subject, governance ownership, validation, applicability, and token eligibility so that no consumer has to infer one concern from another.

Why It Exists​

Stable identity and explicit ownership prevent broken joins, cross-realm ambiguity, and accidental token release when a display key or client-side filter changes.

Where It Fits in Keymate​

Attribute Management owns definitions and applicability data. KEOPS exposes the realm-admin API, while Security and native Keycloak client scopes independently govern token release.

Boundaries​

Definitions do not store every value, select clients, prove effective resolution, or establish general encryption, masking, retention, or compliance controls.

How It Works​

Definition Identity​

An attribute definition describes an attribute; it does not store every value of that attribute. Two identifiers have different jobs:

  • definitionId is the stable system identity used for joins, updates and links.
  • definitionKey is the semantic name used by people, policies and claim configuration.

Do not use definitionKey as a substitute for definitionId. A key can be meaningful and mutable without being safe as record identity.

Subject and Governance Owner​

The subject type identifies the kind of entity described, such as a user or organization. The governance owner identifies the realm-bound scope that controls the definition. They may differ: a tenant can govern a definition whose subject is a user. A value owner is separate again; it is the concrete entity/scope attached to a direct stored value.

The owning provider and realm validate all owner references. The provider does not trust a caller-provided list of owners as an effective inheritance path.

Schema and Behavior​

The current definition contract carries schema and presentation metadata including value type, cardinality, editability, sensitivity, projection target, token eligibility, claim name, validator configuration, a possible default value, and an optimistic version. Applicability records separately describe selector, required contexts, precedence, override and editability policy.

The absence of a matching applicability record means direct-only/no-inheritance. The definition's default and applicability records are resolution inputs; neither is proof of an effective value.

Optimistic Concurrency​

A definition read returns its owner-managed version. Single-definition reads and creates expose the same version as an ETag; definition updates require If-Match and reject a stale version with 412 Precondition Failed. KEOPS #868 is complete: value and applicability mutations now enforce the released optimistic-concurrency contract. Definition delete remains a separate owner-contract gap because its command does not yet accept an expected version; clients must not infer that #868 made an unversioned delete safe.

Filtering Boundary​

The current definition list supports exact key and governance-owner filters with server-side paging and authoritative totals. KEOPS #871 is complete, so released clients consume this bounded result directly and do not reconstruct an authoritative inventory by filtering one page in the browser.

Token Eligibility Is Not Release​

tokenVisible=true only makes a definition eligible for projection. It never means "emit this claim to every token." Release also requires a matching Security bundle/rule, an active native Keycloak client-scope/grant, KEOPS orchestration and mapper support, an allowed token surface, and a resolved value that passes sensitivity, conflict and size policy. See Identity Attributes and Claims.

Unsupported Claims​

The released attribute-definition contract does not establish per-definition encryption-at-rest, encryption-in-transit, UI masking, retention, anonymize-on-delete, or legal-restriction enforcement. This documentation does not present those controls as current product behavior. Document transport and storage security at their actual platform owner, and require separate approved evidence for legal or compliance guarantees.

Diagram​

Example Scenario​

Scenario​

An architect defines a governed user attribute for tenant tenant-a.

Input​

For a user attribute governed by tenant tenant-a:

  • store the stable definition identity as definitionId;
  • use a semantic key such as department as definitionKey;
  • record subjectType=USER and the tenant governance owner independently;
  • treat a default and applicability policy as inputs;
  • show direct values separately from a future server-resolved effective result; and
  • set token eligibility only after the complete release policy is designed.

Expected Outcome​

Consumers use the stable definition identity for joins, keep ownership dimensions separate, and do not infer effective resolution or token release from definition metadata alone.

Common Misunderstandings​

  • "The definition key is the record ID." definitionKey is semantic; definitionId is the stable record identity.
  • "Token visibility releases a claim." It establishes eligibility only; Security policy, native scope/grant, orchestration, and a safe resolved value remain required.

Design Notes / Best Practices​

  • Use definitionId for stable joins and definitionKey for semantic naming.
  • Keep definition governance, direct-value ownership, resolution, and token projection as separate decisions with evidence from their owning components.
  • Treat missing applicability as direct-only/no-inheritance and fail closed when verified context is unavailable.
  • Define a governed attribute without coupling its identity to a mutable display key.
  • Evaluate whether a direct value, default, or applicability rule may contribute to resolution.
  • Configure token eligibility while leaving client-specific release to Security and native scopes.

Attribute Values and Resolution

Separate direct values, defaults, and effective results.

Sensitivity and Data Handling

Understand evidenced sensitivity and release controls.

Attribute Capability Status

Check current evidence and delivery boundaries.