Attribute Definition Model

Summary

Keymate uses a schema-driven approach to declare attributes that attach to users, tenants, and tenant types. Each attribute definition specifies a unique code, bilingual labels, data type, format metadata, allowed values, default value, scope, visibility controls, and compliance metadata. Definitions act as the contract that describes what attribute values the platform manages.

Why It Exists

Unstructured attributes lead to inconsistent data, unpredictable policy evaluations, and compliance gaps. A formal definition model ensures that every attribute has a known schema, that downstream consumers — the policy engine, token projection, admin interfaces, and audit systems — can rely on well-typed, predictable data, and that compliance metadata travels with the definition.

Where It Fits in Keymate

Attribute definitions sit at the foundation of the attribute system. They define the rules; other components consume them:

• Policy Engine — references attribute definitions to evaluate attribute values during authorization decisions.
• Token projection — token claims include attribute values whose definitions permit token visibility.
• Admin interfaces — the admin console renders attribute input fields, labels, and validation feedback based on definition metadata.
• Compliance — definitions carry compliance metadata that drives encryption, masking, and retention behavior across the platform.

Boundaries

The attribute definition model covers:

• Declaring attribute schemas with type, format, and scope
• Controlling visibility across admin interfaces, tokens, and API responses
• Attaching compliance metadata (sensitivity, encryption, retention) to definitions
• Specifying allowed values and validation metadata

The attribute definition model does not cover:

• Storing or resolving attribute values — see Attribute Value Inheritance for how values resolve across scopes
• Consent management workflows or data residency — these are outside the attribute system
• Runtime policy evaluation logic — see Policy Evaluation Model

How It Works

Unique code and bilingual labels

Every attribute definition has a unique code that serves as its stable identifier across the platform. Definitions also carry bilingual display labels and descriptions (Turkish and English), allowing admin interfaces and API responses to present localized attribute information.

Data type and format metadata

Each definition declares a data type that describes what kind of values the attribute holds. Definitions can further describe accepted values through a format specifier and a regular expression pattern. For example, a definition might declare a string type with an email format and a pattern that describes valid values.

Allowed values and localized options

Definitions can specify a list of allowed values, restricting input to a predefined set — useful for attributes like department or role category where free-text input creates inconsistencies. The platform validates submitted values against allowed-values lists (case-insensitive) and rejects values outside the list.

Definitions can also carry localized options as structured data, providing display-ready labels for each allowed value in multiple languages.

Default value

Administrators set a default value at the definition level. The platform uses this value when no explicit value exists for a given scope.

Validation metadata

Each definition carries validation metadata that describes constraints for the attribute:

• Minimum and maximum length — describe acceptable character length boundaries for string values
• Required flag — indicates the attribute is mandatory
• Pattern — a regular expression that describes the expected value format

note

The platform enforces allowed-values validation server-side at write time. Other validation metadata (length constraints, required, pattern) is available for consumers such as admin interfaces to enforce on the client side.

Scope model

Attribute definitions operate across four scopes that determine where values can be set and how they interact:

Scope	Purpose
Global	Platform-wide value that applies unless overridden at a narrower scope
Tenant-scoped	Value specific to a single tenant, overrides the global value for users within that tenant
Global for tenant types	Default value that applies to all tenants of a particular type
Tenant-type-scoped	Value specific to a tenant type within a particular context, overrides the global tenant-type default

See Attribute Value Inheritance for how the platform resolves effective values when multiple scopes carry values for the same attribute.

Visibility and editability

Definitions control where attribute data appears and who can modify it:

• UI visibility — whether the attribute appears in admin console interfaces
• Token visibility — whether the attribute value is projected into access tokens
• Admin visibility — whether the attribute is visible to administrative API consumers
• Editability — whether administrators can modify the attribute value after initial assignment

Login behavior

Administrators can configure definitions to require a value at login time. When enabled, the platform triggers a required action (a Keycloak mechanism that prompts the user to complete a step during authentication) to collect the attribute value. Definitions can also mark an attribute as deferrable, allowing users to skip providing the value during initial registration and supply it later.

Display order and dependencies

Definitions include a display order that controls their sequence in admin interfaces. Definitions can also reference another attribute as a dependency, indicating a prerequisite relationship — for example, indicating that a "department" attribute should be provided before a "sub-department" attribute.

Usage scope

Definitions carry a list of usage scopes that describe where the attribute is consumed across the platform. This metadata helps administrators understand which parts of the system reference a given attribute.

Compliance metadata

Each definition can carry compliance-related settings that drive runtime protections. These include sensitivity classification, encryption controls, retention policies, and legal restriction visibility. See Sensitive Data & Compliance Tags for details on each compliance capability.

Diagram

Example Scenario

Scenario

An administrator creates a "department" attribute definition to standardize department assignments across all tenants. The definition uses an allowed-values list to prevent free-text inconsistencies and sets a global default value.

Input

• Actor: Platform administrator
• Resource: Attribute definition with code department
• Action: Create attribute definition
• Context: Data type set to string, allowed values set to ["Engineering", "Finance", "Human Resources", "Operations"], default value set to "Operations", scope set to global, UI and token visibility enabled, required flag enabled

Expected Outcome

• Applied
• Why: The platform creates the definition and begins enforcing allowed-values validation. Any attempt to set a department value outside the allowed list is rejected. Users without an explicit department value receive the default value "Operations". The policy engine can reference the department attribute in ABAC conditions, and the value appears in token claims for downstream services.

Common Misunderstandings

• "Attribute definitions store values." — Definitions declare the schema and metadata. Values are stored separately, each scoped independently. See Attribute Value Inheritance.
• "Scope on the definition restricts where it can be used." — Scope determines at which levels values can be set and how inheritance resolves, not where the definition itself is visible.
• "All validation metadata is enforced server-side." — The platform enforces allowed-values validation at write time. Consumers such as admin UI forms can enforce other validation metadata (length constraints, required, pattern) on the client side.

warning

Attribute codes are the stable identifier used across policies, token projections, and integrations. Changing an attribute code after it is referenced in policies or downstream systems requires updating all consumers.

Design Notes / Best Practices

• Use allowed-values lists for categorical attributes such as department, role category, or status. This prevents free-text drift and makes policy conditions predictable.
• Set appropriate scope for each definition. Use global scope for platform-wide attributes and tenant-scoped for attributes that vary by tenant.
• Enable token visibility selectively. Only project attributes into tokens that downstream services need for authorization decisions — unnecessary claims increase token size.
• Mark compliance metadata early. Configure sensitivity, encryption, and retention settings when creating the definition rather than retrofitting them after values exist.

tip

Define allowed values as strictly as your use case allows. The platform enforces allowed-values validation server-side and prevents data quality issues from propagating into policy evaluations and downstream systems.

Related Use Cases

• Creating a standardized attribute schema for a new tenant onboarding workflow
• Defining a sensitive attribute (national ID) with encryption and masking requirements
• Adding a new attribute to feed ABAC policy conditions for resource-level authorization
• Configuring bilingual attribute labels for a platform serving Turkish and English-speaking users

Related Docs

Attribute Value Inheritance

How attribute values resolve across scopes with override priority

Sensitive Data & Compliance Tags

Compliance metadata on definitions that drives encryption, masking, and retention

Authorization Concepts

How attributes feed into ABAC policy evaluation

Glossary — Attribute

Platform-wide definition of an attribute