Form

A Form is a JSON Schema–based definition that describes the structure, validation rules, and presentation of a data object in tSM. Forms are the foundation of every dynamic attribute in the platform — every Characteristics references exactly one Form.

What it's for

• Schema definition — declares the shape of data (fields, types, nesting, enumerations, required/optional) using JSON Schema.
• UI rendering — drives automatic form generation in tSM detail pages, dialogs, dashboards, and custom widgets.
• Validation — enforces data constraints at creation and update time across all channels (UI, API, process engine).
• Reuse — the same Form can be referenced by multiple Characteristics and used in different Entity Specifications.

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

For a comprehensive guide on designing forms (JSON Schema authoring, widgets, conditional logic), see the Form Designer section.

---

Form types

formType	Description
FORM	Standard form — the most common type, used for entity detail pages and characteristics.
DIALOG	Dialog form — rendered in a modal dialog (e.g., confirmation steps, quick-edit overlays).
DASHBOARD	Dashboard form — used for dashboard widget configuration and layout.
CUSTOM_FIELD	Custom field — a single-field form used inline (e.g., a specialized input control).
PAGE	Full-page form — rendered as a standalone page (e.g., a wizard or multi-step form).

---

Key concepts

JSON Schema (schema)

The schema field holds the full JSON Schema definition. This is the core of every Form — it declares:

• Properties — fields with their types (string, number, boolean, object, array).
• Validation — required, minLength, maxLength, pattern, enum, minimum/maximum.
• Nesting — complex objects and arrays of objects for hierarchical data.
• UI hints — custom x-* extensions for widget selection, layout, and conditional visibility.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Contact Info",
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "format": "email",
      "description": "Primary email address"
    },
    "phone": {
      "type": "string",
      "pattern": "^\\+?[0-9\\s-]+$"
    }
  },
  "required": ["email"]
}

Base Form (baseForm)

A Form can inherit from another Form via baseForm (FK to another Form's code). This supports composition — define common fields once and extend them in specialized forms.

Entity Type binding (entityType)

A Form can be linked to a specific entityType, indicating which kind of entity it is designed for. This helps the platform filter and suggest relevant forms in the UI.

Characteristics back-reference

The read-only characteristics list shows which Characteristics reference this Form. This is useful for impact analysis — before modifying a Form schema, you can check which Characteristics (and therefore which Entity Specifications) are affected.

---

Settings and configuration

Field	Purpose
config	General-purpose key/value configuration metadata.
settings	Form-level settings that control rendering behavior, layout options, and other display parameters.
exampleValue	A sample valid value conforming to the schema — useful for documentation, testing, and as a template for callers.

---

Reference

Form (attributes)

Field	Type	Required	Read-only	Description / Notes
id	UUID	–	–	Identifier (not for end-user display).
code	String	Yes	–	Unique ASCII code (no spaces). Referenced by Characteristics, Entity Specifications, and processes.
name	String	Yes	–	Human-readable name shown in admin UI.
description	String	–	–	Optional longer description / tooltip.
schema	Object	Yes	–	JSON Schema definition.
formType	Enum	–	–	FORM, DIALOG, DASHBOARD, CUSTOM_FIELD, PAGE.
baseForm	String	–	–	Code of a parent Form to inherit from (FK Form.code).
entityType	String	–	–	Code of the EntityType this form is designed for (FK EntityType.code).
configType	String	Yes	–	Business package this form belongs to (FK ConfigType.code).
characteristics	List	–	Yes	Codes of Characteristics that reference this form (computed back-reference).
exampleValue	Any	–	–	Sample valid value of this form (for documentation and testing).
config	Map	–	–	General metadata.
settings	Map	–	–	Form-level rendering/behavior settings.
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.
localizationData	Object	–	–	Translations for name / description.
auditInfo	Object	–	Yes	Standard audit metadata.

---

Good Practices

• Stable code — Characteristics and other configuration entities reference forms by code; renaming breaks callers.
• Use configType — always assign a ConfigType so the form appears in the correct business package in admin UI.
• Provide exampleValue — helps developers and configurators understand the expected data shape without reading the full schema.
• Keep schemas focused — one form per logical data block. Compose complex configurations using multiple Characteristics on an Entity Specification.
• Leverage baseForm — factor out shared field groups (e.g., address, contact info) into a base form and extend it in specialized forms.
• Check characteristics before editing — the back-reference list tells you which Characteristics (and downstream Entity Specifications) will be affected by schema changes.
• Tag consistently — use dataTags to distinguish form purposes (core, integration, custom-fields).

---

See Also

• Form Designer — visual tool for authoring JSON Schemas.
• Characteristics — the dynamic attribute that wraps a Form.
• Entity Specification — groups Characteristics into a profile.
• Entities & Characteristics (Architecture) — conceptual overview of the TM Forum pattern.