Characteristics

A Characteristics is a named dynamic attribute that extends an entity beyond its core fields. Each Characteristics wraps a Form (JSON Schema) and adds metadata controlling how the attribute is stored, indexed, secured, and displayed.

What it's for

• Data model extension — add new attributes to any entity type without modifying core database tables.
• Schema governance — each attribute has a formal JSON Schema (via its Form), enforcing validation across all channels.
• Access control — per-attribute read and write privileges.
• Search & indexing — per-attribute ElasticSearch mapping control.
• Display ordering — controls the position of the attribute on forms.

Characteristics are first-class configuration entities — they have validity, localization, audit trail, and can be organized with dataTags and configType.

For the architectural context, see Entities & Characteristics.

---

Key concepts

attributeName

The attributeName is the key under which the characteristic's value is stored in the entity's dynamic data. It acts as a stable contract between the configuration and the runtime:

• Must be unique within a given EntityType.
• Referenced by processes, SpEL scripts, and API consumers to read/write the value.
• Across Entity Specifications of the same EntityType, characteristics with the same attributeName must be identical to ensure consistent data interpretation.

Form reference

Every Characteristics points to exactly one Form via the form field (FK Form.code). The Form's JSON Schema defines what data the characteristic accepts and how it is rendered.

Privileges

Field	Purpose
editPrivilege	Privilege code required to write this attribute. If unset, all users with entity-edit access can write it.
readPrivilege	Privilege code required to read this attribute. If unset, all users with entity-view access can see it.
readonly	When true, the attribute is displayed but cannot be edited in the UI (regardless of privileges).

ElasticSearch indexing (indexMapping)

Controls how the characteristic's value is indexed in ElasticSearch:

Value	Description
UNTYPED	Indexed as a generic (keyword/text) field — suitable for most cases.
TYPED	Indexed with a type-specific mapping (number, date, boolean) enabling range queries and aggregations.
NONE	Not indexed — the value is stored but not searchable via ElasticSearch.

Choose TYPED when you need numeric ranges, date filtering, or sorting on this attribute.

---

Characteristic values

For characteristics that use enumerated values (dropdowns, radio buttons), a set of Characteristic Values can be defined. Each value specifies:

Field	Type	Description
id	UUID	Unique identifier.
value	String	The stored value.
valueName	String	Display label for the value.
isDefault	Bool	Whether this is the default selection.
unitOfMeasure	String	Optional unit (e.g., GB, Mbps).
validFor	TimePeriod	Optional validity window for the value.
rangeInterval	String	Optional range specification.
characteristicsId	UUID	Parent Characteristics this value belongs to.
data	Map	Additional data for the value.
auditInfo	Object	Standard audit metadata.

This follows the TM Forum CharacteristicSpecValue pattern — predefined controlled values ensuring data consistency.

---

Reference

Characteristics (attributes)

Field	Type	Required	Read-only	Description / Notes
id	UUID	–	–	Identifier (not for end-user display).
code	String	Yes	–	Unique ASCII code (no spaces). Used to reference the characteristic from Entity Specifications and API.
name	String	Yes	–	Human-readable name shown in admin UI.
description	String	–	–	Optional tooltip / longer description.
title	String	–	–	Default title displayed on forms (up to 255 chars).
attributeName	String	Yes	–	Key under which the value is stored in entity data. Must be unique within an EntityType.
form	String	–	–	Code of the Form (JSON Schema) backing this characteristic (FK Form.code).
configType	String	–	–	Business package this characteristic belongs to (FK ConfigType.code).
editPrivilege	String	–	–	Privilege required to write this attribute.
readPrivilege	String	–	–	Privilege required to read this attribute.
readonly	Bool	–	–	If true, the attribute is displayed but not editable.
indexMapping	String	Yes	–	ElasticSearch mapping: UNTYPED, TYPED, or NONE.
defaultOrder	Int	–	–	Display order on forms. Default 50.
configurable	Bool	–	–	Whether the characteristic is configurable.
unique	Bool	–	–	Whether the value must be unique across entities.
required	Bool	–	–	Whether the value is mandatory.
extensible	Bool	–	–	Whether the characteristic can be extended.
draft	Bool	–	–	Whether the characteristic is in draft state.
schemaLocation	String	–	–	Optional schema location reference.
dataTags	List	–	–	Labels for grouping and filtering.
validityFrom/To	Date	–	–	Optional validity window.
valid	Bool	–	Yes	Computed from validity; true when within the validity interval.
config	Map	–	–	Additional metadata.
localizationData	Object	–	–	Translations for name / description.
auditInfo	Object	–	Yes	Standard audit metadata.

---

Good Practices

• Stable code and attributeName — both are referenced by Entity Specifications, processes, and API consumers. Renaming breaks existing data and integrations.
• One Characteristics per logical attribute — keep each characteristic focused on a single concept. Compose complex profiles in Entity Specifications.
• Consistent attributeName within an EntityType — if the same attributeName appears in multiple Entity Specifications of the same EntityType, the Characteristics must be identical.
• Set privileges deliberately — use editPrivilege / readPrivilege for sensitive fields (e.g., financial data, personal information).
• Choose indexMapping wisely — TYPED enables rich queries but increases index size. Use NONE for large text blobs that don't need search.
• Use defaultOrder — explicitly set display order to control the layout. Relying on the default (50) for all characteristics leads to unpredictable ordering.
• Tag consistently — use dataTags to categorize characteristics (core, integration, customer-facing).

---

See Also

• Form — the JSON Schema backing a characteristic.
• Entity Specification — groups characteristics into a profile.
• Entities & Characteristics (Architecture) — conceptual overview of the TM Forum Characteristics pattern.
• ConfigType — business packaging for configuration entities.