Form Configuration

Booker4j uses YAML files to define every aspect of a booking form — structure, field types, validation rules, branching logic, and DTO mapping. No code changes are needed to create or modify a form.

File Location

Form configs live in src/main/resources/form/config/customers/{customerId}.yaml. Each customer (tenant) has its own config file. Changes are picked up automatically via cache-based hot-reload.

Top-Level Structure

Every config file has 5 sections:

version: '1.0'           # Schema version

metadata:                 # Business context and audit info
  lastUpdated: '2024-01-15'
  businessOwner: Operations Team
  description: Cleaning service booking form
  businessNameKey: business.cleaning.name
  businessDescriptionKey: business.cleaning.description
  chatbotRoleKey: business.cleaning.role

defaults:                 # DTO mapping and mandatory field rules
  dtoFields: [serviceType, date, name, email, phone]
  persistOthersTo: extras
  mandatory: [serviceType, date, name, email]

formFlow:                 # The form's question tree (order + branching)
- serviceType:
    cleaning:
    - preferredDate: {}
    maintenance:
    - issueType: {}
- name: {}
- email: {}
- phone: {}

fieldDefinitions:         # Properties for each field (type, validation, prompts)
  serviceType:
    type: select
    promptKey: fields.serviceType.ask
    labelKey: fields.serviceType.label
    descriptionKey: fields.serviceType.description
  # ... more fields

Version

Key	Type	Required	Valid Values
version	String	Yes	'1.0', '2.0'

Schema version for parser compatibility. Both versions are fully backwards-compatible.

Metadata

Business context used by the LLM to generate personalized greetings and responses.

Key	Type	Required	Description	Example
lastUpdated	String	Yes	ISO 8601 date for audit trail	'2024-01-15'
businessOwner	String	Yes	Responsible team or person	'Operations Team'
description	String	Yes	Human-readable config description	'Cleaning service booking form'
businessNameKey	String	Yes	Translation key for business name	'business.cleaning.name'
businessDescriptionKey	String	Yes	Translation key for business description	'business.cleaning.description'
chatbotRoleKey	String	Yes	Translation key for chatbot role/personality	'business.cleaning.role'

All *Key fields are dot-notation translation keys resolved from translations/{locale}.yaml.

Defaults

Controls how form answers are mapped to the submission DTO and which fields are mandatory.

Key	Type	Required	Description
dtoFields	List of strings	Yes	Field names that go into the main DTO fields map
persistOthersTo	String	Yes	Key name for the extras map (must be "extras")
mandatory	List of strings	Yes	Fields that must be answered before the form is complete

Validation Rules

• Every field in mandatory must also be in dtoFields
• persistOthersTo must NOT be in dtoFields
• No duplicate entries in dtoFields or mandatory

Quick Start

Here's a minimal working config for a 4-field booking form with one branch:

version: '1.0'
metadata:
  lastUpdated: '2024-06-01'
  businessOwner: Dev Team
  description: Simple appointment booking
  businessNameKey: business.mycompany.name
  businessDescriptionKey: business.mycompany.description
  chatbotRoleKey: business.mycompany.role
defaults:
  dtoFields: [appointmentType, date, name, email]
  persistOthersTo: extras
  mandatory: [appointmentType, date, name, email]
formFlow:
- appointmentType:
    consultation:
    - preferredDate: {}      # shown if "consultation" selected
    followUp:
    - preferredDate: {}      # shown if "followUp" selected
- name: {}                   # always shown (common field)
- email: {}                  # always shown (common field)
fieldDefinitions:
  appointmentType:
    type: select
    dtoField: appointmentType
    promptKey: fields.appointmentType.ask
    labelKey: fields.appointmentType.label
    descriptionKey: fields.appointmentType.description
  consultation:
    type: info
    promptKey: services.consultation.prompt
    labelKey: services.consultation.label
    descriptionKey: services.consultation.description
  followUp:
    type: info
    promptKey: services.followUp.prompt
    labelKey: services.followUp.label
    descriptionKey: services.followUp.description
  preferredDate:
    type: date
    dtoField: date
    promptKey: fields.date.ask
    labelKey: fields.date.label
    descriptionKey: fields.date.description
    validation:
      required: true
      minAdvanceHours: 24
  name:
    type: text
    promptKey: fields.name.ask
    labelKey: fields.name.label
    descriptionKey: fields.name.description
    validation:
      required: true
      minLength: 2
  email:
    type: email
    promptKey: fields.email.ask
    labelKey: fields.email.label
    descriptionKey: fields.email.description
    validation:
      required: true

Next Steps

• Field Types — All 10 field types with examples
• Validation Rules — Validation rule reference and compatibility matrix
• FormFlow & Branching — Tree structure, conditional branches, nesting
• DTO Mapping — How answers become the submission DTO