Dynamic Forms (FRM)

The frm submodule of sys provides a metadata-driven form and grid system. Administrators define reusable typed properties, group them into schemas, lay them out as forms or grids, and store user-entered data as JSON-backed records that conform to those schemas. It is the backing model for free-form business documents (brand, persona, audience, equipment, inspection, campaign, …) and exposes its schemas to the Venlo Frame as DictionarySchema instances so the rest of the framework can render and validate values uniformly.

Concepts

Property: A reusable typed value descriptor (text, number, date, enumerate, …). Properties carry the rules that govern a value: string length and case, decimal precision/scale/rounding, default UI dimensions, optional unit of measure, and — for enumerate properties — the allowed options.
Schema: The structural definition of a record type: an ordered list of fields, each bound to a Property. A schema corresponds to one DictionarySchema at runtime.
Schema Field: A named slot inside a schema. It refers to a Property for typing rules and adds schema-specific concerns: line order, label, tooltip, mandatory/optional status, and an optional LLM-assist prompt used to fill the field automatically.
Form: A user-interface layout for entering data into a schema. A form is an ordered tree of sections; each section contains form fields that point at schema fields.
Grid: A user-interface layout for displaying schema data as a table. A grid lists which schema fields appear as columns and in what order.
Record: A concrete instance of a schema. Record values are stored as JSON (DomainRecordValue); the schema interprets the JSON into typed values.
Field Status: Whether a schema field is Inactive, Mandatory, or Optional for data entered against the schema.

Entities

Domain Schema Type (`DomainSchemaType`)

Top-level category that groups related schemas (for example "marketing", "trade").

Field Description

Field	Description
`code`	Business key (up to 12 characters).
`description`	Human-readable name.

code

Business key (up to 12 characters).

description

Human-readable name.

Domain Schema (`DomainSchema`)

The structural definition of a record type. A schema belongs to a DomainSchemaType and owns an ordered set of schema fields. At runtime it is converted to an io.venlo.domain.dictionary.DictionarySchema so the framework can read, write, and validate values.

Field Description

Field	Description
`code`	Business key (up to 12 characters).
`description`	Human-readable name.
`domainSchemaType`	Type/category the schema belongs to.
`jsonSchema`	Optional JSON Schema document; reserved for external schema export/validation.
`domainSchemaFields`	Operational back-reference to the fields that make up this schema.

code

Business key (up to 12 characters).

description

Human-readable name.

domainSchemaType

Type/category the schema belongs to.

jsonSchema

Optional JSON Schema document; reserved for external schema export/validation.

domainSchemaFields

Operational back-reference to the fields that make up this schema.

Domain Schema Field (`DomainSchemaField`)

One field of a schema. It binds a DomainProperty for typing rules and adds schema-specific concerns such as ordering, labels, mandatory/optional status, and LLM-assist prompts.

Field Description

Field	Description
`domainSchema`	Owning schema (business key, plus `lineNumber`).
`lineNumber`	Order of the field within the schema.
`code`	Field code (up to 24 characters), used as the JSON key in records.
`description`	Field label shown in forms and grids.
`fieldTooltip`	Optional tooltip shown next to the field.
`domainProperty`	The typed property providing value rules and (for enumerates) options.
`domainFieldStatus`	Whether the field is inactive, mandatory, or optional.
`llmPromptPrefix`	Optional short text prepended to the LLM prompt when this field is filled by AI.
`llmAssistPrompt`	Optional full prompt used when an LLM is asked to fill this field for a record.

domainSchema

Owning schema (business key, plus lineNumber).

lineNumber

Order of the field within the schema.

code

Field code (up to 24 characters), used as the JSON key in records.

description

Field label shown in forms and grids.

fieldTooltip

Optional tooltip shown next to the field.

domainProperty

The typed property providing value rules and (for enumerates) options.

domainFieldStatus

Whether the field is inactive, mandatory, or optional.

llmPromptPrefix

Optional short text prepended to the LLM prompt when this field is filled by AI.

llmAssistPrompt

Optional full prompt used when an LLM is asked to fill this field for a record.

The lookup DomainSchema.getField(code) returns the schema field for a given field code, or raises a business exception if it does not exist.

Domain Property (`DomainProperty`)

A reusable typed value descriptor. Multiple schema fields can share the same property to keep typing rules consistent across schemas.

Field Description

Field	Description
`code`	Business key (up to 12 characters).
`description`	Short label.
`descriptionLong`	Longer description used in tooltips and AI context.
`domainUom`	Optional unit of measure (e.g. for decimal properties).
`valueType`	The kind of value this property holds — see Value Types below.
`stringLength`	Maximum length for `String` values.
`stringUpperCase`	Whether `String` values are forced to upper case.
`decimalPrecision`	Total digits for `Decimal` values.
`decimalScale`	Digits after the decimal point for `Decimal` values.
`decimalRounding`	Rounding mode applied to `Decimal` values (`HALF_UP`, `DOWN`, …).
`defaultWidthChar`	Default editor width in characters (for text-style values).
`defaultHeightLines`	Default editor height in lines (for text-style values).
`internalNotes`	Free-form notes for administrators; not shown to end users.

code

Business key (up to 12 characters).

description

Short label.

descriptionLong

Longer description used in tooltips and AI context.

domainUom

Optional unit of measure (e.g. for decimal properties).

valueType

The kind of value this property holds — see Value Types below.

stringLength

Maximum length for String values.

stringUpperCase

Whether String values are forced to upper case.

decimalPrecision

Total digits for Decimal values.

decimalScale

Digits after the decimal point for Decimal values.

decimalRounding

Rounding mode applied to Decimal values (HALF_UP, DOWN, …).

defaultWidthChar

Default editor width in characters (for text-style values).

defaultHeightLines

Default editor height in lines (for text-style values).

internalNotes

Free-form notes for administrators; not shown to end users.

Value Types (`DomainValueType`)

Code Name Meaning

Code	Name	Meaning
`BO`	Boolean	True/false flag.
`DA`	Date	Calendar date.
`DT`	Date Time	Date plus time of day (minute precision).
`DE`	Decimal	Fixed-precision number; uses `decimalPrecision`/`decimalScale`/`decimalRounding`.
`EN`	Enumerate	One value chosen from this property’s `DomainPropertyOption` list.
`IN`	Integer	32-bit integer.
`JS`	Json	Raw JSON value.
`LO`	Long	64-bit integer.
`SH`	Short	16-bit integer.
`ST`	String	Single-line text; uses `stringLength`/`stringUpperCase`.
`TA`	Ascii	Multi-line plain ASCII text.
`TC`	Css	Multi-line CSS source.
`TH`	Html	Multi-line HTML source.
`TJ`	JavaScript	Multi-line JavaScript source.
`TM`	Markdown	Multi-line Markdown source.
`TV`	CSV	Multi-line CSV content.
`R`	Reference	Reference to another entity (reserved; not currently materialized as a record value).

BO

Boolean

True/false flag.

DA

Date

Calendar date.

DT

Date Time

Date plus time of day (minute precision).

DE

Decimal

Fixed-precision number; uses decimalPrecision/decimalScale/decimalRounding.

EN

Enumerate

One value chosen from this property’s DomainPropertyOption list.

IN

Integer

32-bit integer.

JS

Json

Raw JSON value.

LO

Long

64-bit integer.

SH

Short

16-bit integer.

ST

String

Single-line text; uses stringLength/stringUpperCase.

TA

Ascii

Multi-line plain ASCII text.

TC

Css

Multi-line CSS source.

TH

Html

Multi-line HTML source.

TJ

JavaScript

Multi-line JavaScript source.

TM

Markdown

Multi-line Markdown source.

TV

CSV

Multi-line CSV content.

R

Reference

Reference to another entity (reserved; not currently materialized as a record value).

Domain Property Option (`DomainPropertyOption`)

An allowed value for an enumerate property. Options also carry an optional LLM prompt that helps an AI assistant pick the option for a field.

Field Description

Field	Description
`domainProperty`	Owning property (business key, plus `code`).
`code`	Option code (up to 4 characters), persisted as the field value.
`description`	Human-readable label for the option.
`sortSequence`	Optional ordering hint for the option list.
`llmOptionPrompt`	Optional prompt segment used when an LLM evaluates whether to pick this option.

domainProperty

Owning property (business key, plus code).

code

Option code (up to 4 characters), persisted as the field value.

description

Human-readable label for the option.

sortSequence

Optional ordering hint for the option list.

llmOptionPrompt

Optional prompt segment used when an LLM evaluates whether to pick this option.

Domain Unit of Measure (`DomainUom`)

A unit attached to numeric or text properties to clarify what the value represents (for example "kg", "%", "min").

Field Description

Field	Description
`code`	Business key (up to 8 characters).
`description`	Human-readable name.

code

Business key (up to 8 characters).

description

Human-readable name.

Domain Form (`DomainForm`)

A user-interface layout that captures data for one schema. A form has one or more sections, which can themselves nest.

Field Description

Field	Description
`code`	Business key (up to 12 characters).
`description`	Human-readable name.
`domainSchema`	The schema whose fields this form lays out.

code

Business key (up to 12 characters).

description

Human-readable name.

domainSchema

The schema whose fields this form lays out.

Domain Form Section (`DomainFormSection`)

A section within a form — visually a fieldset/group. Sections can be nested via parentFormSection.

Field Description

Field	Description
`domainForm`	Owning form (business key, plus `sectionNumber`).
`sectionNumber`	Order of the section within the form.
`description`	Section title displayed in the UI.
`parentFormSection`	Optional parent section, enabling nested groups.

domainForm

Owning form (business key, plus sectionNumber).

sectionNumber

Order of the section within the form.

description

Section title displayed in the UI.

parentFormSection

Optional parent section, enabling nested groups.

Domain Form Field (`DomainFormField`)

One field placement inside a section. It points at a DomainSchemaField; the section’s order plus fieldNumber determine where it appears on screen.

Field Description

Field	Description
`domainFormSection`	Owning section (business key, plus `fieldNumber`).
`fieldNumber`	Order of the field within the section.
`domainSchemaField`	The schema field rendered at this position.

domainFormSection

Owning section (business key, plus fieldNumber).

fieldNumber

Order of the field within the section.

domainSchemaField

The schema field rendered at this position.

Domain Grid (`DomainGrid`)

A table layout used to list records of a schema.

Field Description

Field	Description
`code`	Business key (up to 12 characters).
`description`	Human-readable name.
`domainSchema`	The schema whose fields this grid columns are taken from.

code

Business key (up to 12 characters).

description

Human-readable name.

domainSchema

The schema whose fields this grid columns are taken from.

Domain Grid Column (`DomainGridColumn`)

One column placement within a grid.

Field Description

Field	Description
`domainGrid`	Owning grid (business key, plus `fieldNumber`).
`fieldNumber`	Order of the column from left to right.
`domainSchemaField`	The schema field shown in this column.

domainGrid

Owning grid (business key, plus fieldNumber).

fieldNumber

Order of the column from left to right.

domainSchemaField

The schema field shown in this column.

Domain Record (`DomainRecord`)

A concrete data instance for a schema. The values are stored as JSON in recordValue; the schema interprets the JSON into typed values when the record is read.

Field Description

Field	Description
`guid`	Globally-unique business key.
`domainSchema`	The schema this record conforms to.
`recordValue`	JSON document containing the record’s field values, keyed by schema-field code.

guid

Globally-unique business key.

domainSchema

The schema this record conforms to.

recordValue

JSON document containing the record’s field values, keyed by schema-field code.

Domain Field Status (`DomainFieldStatus`)

Code Name Meaning

Code	Name	Meaning
`I`	Inactive	The field exists but is hidden from data entry and listings.
`M`	Mandatory	The field must be filled when entering data.
`O`	Optional	The field may be left empty.

I

Inactive

The field exists but is hidden from data entry and listings.

M

Mandatory

The field must be filled when entering data.

O

Optional

The field may be left empty.

Functionality

Schema-to-Dictionary conversion

DomainSchemaConverter.toDictionarySchema(…) (exposed via SYS_FRM_Util.toDictionarySchema) converts a DomainSchema into a Venlo DictionarySchema. For each schema field it derives a typed ValueTypeMeta from the field’s DomainProperty — for example, String properties become a StringMeta carrying the property’s length and upper-case flag, and Decimal properties become a DecimalMeta carrying precision, scale, and rounding mode. The resulting DictionarySchema is what the rest of the framework uses to read, write, and validate record values.

Reference (R) properties are not currently convertible and raise an internal exception if encountered; they are reserved for future cross-entity references.

Domain record creation

DomainRecordWriterService.createDomainRecord(schema, recordValue) creates a new DomainRecord with a fresh GUID, links it to the supplied schema, and persists it. The caller is responsible for producing a JSON DomainRecordValue whose keys match the schema’s field codes.

JSON record-set wrappers

Two helper classes simplify reading and writing record-set JSON in service code:

JsonValueMapListWrapper: Parses a JSON array of objects into a mutable list of Map<String, Object>. Provides record-level access by index (getValue, setValue, addRecord) and serialization back to JSON. Used when typing rules are not needed.
JsonDictionaryListWrapper: Wraps a JsonValueMapListWrapper with a DictionarySchema. getValue and setValue go through DictionaryUIConverter so callers exchange typed Java values (e.g. BigDecimal, LocalDate) instead of raw JSON primitives. This is the standard way to manipulate record values once a schema is available.

LLM-assist prompt construction

DomainSchemaReaderService.createDomainSchemaFieldAssistPrompt(…) is the entry point for building the prompt that asks an LLM to fill a single field of a record, using the field’s llmPromptPrefix, llmAssistPrompt, and any enumerate option’s llmOptionPrompt. The current implementation returns an empty string and is a placeholder for the upcoming LLM-driven form-filling feature.

Public API

`SYS_FRM_QueryApi`

Read-side facade for other modules.

Method Description

Method	Description
`findDomainSchemaByCode(Code12)`	Returns the schema with the given code, or `null` if absent.
`findDomainSchemaByCodeMandatory(Code12)`	Same as above but raises a business exception if not found.
`createDomainSchemaFieldAssistPrompt(…)`	Delegates to `DomainSchemaReaderService` (currently a placeholder).

findDomainSchemaByCode(Code12)

Returns the schema with the given code, or null if absent.

findDomainSchemaByCodeMandatory(Code12)

Same as above but raises a business exception if not found.

createDomainSchemaFieldAssistPrompt(…)

Delegates to DomainSchemaReaderService (currently a placeholder).

`SYS_FRM_CommandApi`

Write-side facade for other modules.

Method Description

Method	Description
`createDomainRecord(DomainSchema, DomainRecordValue)`	Persists a new record under the given schema and returns it.

createDomainRecord(DomainSchema, DomainRecordValue)

Persists a new record under the given schema and returns it.

`SYS_FRM_Util`

Static utility for converting a DomainSchema to a Venlo DictionarySchema. Used wherever the framework needs to render or validate record values for a schema.

Method Description

Method	Description
`toDictionarySchema(DomainSchema)`	Returns the framework `DictionarySchema` derived from the given domain schema.

toDictionarySchema(DomainSchema)

Returns the framework DictionarySchema derived from the given domain schema.

`SYS_FRM_Constant`

Currently contains no constants.

ViewModel actions

The submodule defines view models (DomainSchemaViewModel, DomainPropertyViewModel, DomainFormViewModel, …) for the standard CRUD pages, but does not declare any custom UI actions. There are no buttons specific to this submodule beyond the default toolbar.

Dynamic Forms (FRM)

Concepts

Entities

Domain Schema Type (DomainSchemaType)

Domain Schema (DomainSchema)

Domain Schema Field (DomainSchemaField)

Domain Property (DomainProperty)

Value Types (DomainValueType)

Domain Property Option (DomainPropertyOption)

Domain Unit of Measure (DomainUom)

Domain Form (DomainForm)

Domain Form Section (DomainFormSection)

Domain Form Field (DomainFormField)

Domain Grid (DomainGrid)

Domain Grid Column (DomainGridColumn)

Domain Record (DomainRecord)

Domain Field Status (DomainFieldStatus)

Functionality

Schema-to-Dictionary conversion

Domain record creation

JSON record-set wrappers

LLM-assist prompt construction

Public API

SYS_FRM_QueryApi

SYS_FRM_CommandApi

SYS_FRM_Util

SYS_FRM_Constant

ViewModel actions

Domain Schema Type (`DomainSchemaType`)

Domain Schema (`DomainSchema`)

Domain Schema Field (`DomainSchemaField`)

Domain Property (`DomainProperty`)

Value Types (`DomainValueType`)

Domain Property Option (`DomainPropertyOption`)

Domain Unit of Measure (`DomainUom`)

Domain Form (`DomainForm`)

Domain Form Section (`DomainFormSection`)

Domain Form Field (`DomainFormField`)

Domain Grid (`DomainGrid`)

Domain Grid Column (`DomainGridColumn`)

Domain Record (`DomainRecord`)

Domain Field Status (`DomainFieldStatus`)

`SYS_FRM_QueryApi`

`SYS_FRM_CommandApi`

`SYS_FRM_Util`

`SYS_FRM_Constant`