Variable Types and Field Design

Whether document forms can be implemented in a stable, scalable way depends on more than just “can we insert variables”. The bigger question is whether the template design phase already settles field semantics, naming rules, value shapes, and risk boundaries.

What This Page Covers

• Choose the right variable type before worrying about validation rules
• Design name / key / description / required in a stable way from day one
• The way fields are constrained during template design directly affects the stability of filling, programmatic population, and export later on

Quick Selection Guide

This page answers three practical questions:

1. Which variable type should you choose?
2. How should name / key / description / required be designed?
3. What kind of field design remains stable for manual filling, programmatic population, and export?

1. First, Separate Variables into Two Broad Groups

In the current implementation, variables fall into two major groups:

Text-like Variables

The supported base types include:

• text
• number
• date
• richtext
• radio
• checkbox
• select

These are a good fit for:

• Names, departments, amounts, dates, codes, and explanations
• Single-choice states, multi-choice values, and selects
• Localized complex content through rich text

Text-like Variables Also Support Formatting

This is an important point: text-like variables are not just data slots that get replaced with a value. They can directly inherit the inline formatting already present in the document body.

Based on the current implementation, text variables preserve the text marks on the current node when they are inserted and updated, and those marks are also preserved in the generated result. In practice, that means you can treat a text variable as styled dynamic text rather than a plain placeholder.

This is especially useful for:

• Bold, italic, underline, and strikethrough
• Text color and background highlight
• Keeping the variable visually aligned with the surrounding font, size, and inline styles

Typical high-value scenarios include:

• Dynamic fields in a contract title need to keep the same emphasis as the fixed title text
• Amounts, dates, and risk notices need stronger visual emphasis
• In notices, letters, and certificates, variable values should match the surrounding layout rather than looking like foreign placeholders

It also helps to separate two different concerns:

• Body styling: applied directly in the document, best for controlling final appearance
• Field rules: configured in the right-side variable panel, best for controlling validation, date formatting, range separators, options, and similar behavior

In short, text variables support both value constraints and display formatting.

Image-like Variables

The supported base types include:

• image
• signature
• stamp
• qrcode
• barcode

These are a good fit for:

• Uploaded images or image attachments
• Handwritten signatures
• Official stamps
• Business QR codes
• Barcodes

Image-like Variables Support Attribute Settings

Image-like variables are not just places to drop in an image. In design mode, the variable panel on the right supports a second layer of configuration beyond the basic field metadata.

The currently available attribute settings include:

• Width and height
• Auto height
• Equal proportion scaling
• Floating drag behavior
• Common size presets for stamp variables

These settings are highly practical because image-like variables often determine how professional the final page layout looks. For example:

• Attachment screenshots usually work best with a fixed width plus auto height so they do not stretch out of shape
• Signature areas are often better at a smaller size so they do not take over the surrounding paragraph
• Seal areas often need a stable visual size so the template can reserve enough room in advance
• QR codes and barcodes usually need deliberate size control to keep printing and scanning reliable

From a template-design perspective, image variables should always be considered from at least two angles:

• What business meaning they carry, such as attachment, signature, seal, QR code, or barcode
• What size and layout behavior they should have inside the document

That is why image-variable attribute settings are so useful in real business documents. They directly affect the final document appearance and export quality.

2. Choose by Business Meaning First

The recommended order is not “anything that works is fine”. It is “choose the type that best matches the business meaning and is easiest to constrain”.

Plain Text

Best for:

• Names
• Departments
• Titles
• Short descriptions

Not ideal for:

• Amounts or quantities that should behave as numbers
• Fields that clearly require date formatting
• Values that should always come from a fixed option list

Number

Best for:

• Amounts
• Quantities
• Ratios
• Years, months, and days

Where possible, prefer built-in rule types over a generic “number”, for example:

• Positive integer
• Non-negative integer
• Two-decimal number
• Percentage

This moves errors into the filling stage instead of discovering them only after submission.

Date

Best for:

• Effective dates
• Application dates
• Signing dates
• Start/end time ranges

If the business meaning is “single date / date range / time / time range”, choose the semantically correct date type directly rather than treating everything as plain text.

Option Types: radio / checkbox / select

Best for:

• Status
• Categories
• Outcomes
• Tags
• Multi-select checklists

If the candidate values are fixed, prefer option-based variables instead of free typing.

Rich Text

Best for:

• Complex tables generated by code
• Multi-paragraph explanations
• Formatted clause blocks

Not recommended:

• As a freeform manual input type for regular fillers

The reason is that rich text structures are more complex, the content source is harder to control, and they are more likely to introduce unstable behavior during population, preview, or export.

Image-like Variables

Best for:

• Uploaded business images
• Signature confirmation
• Official stamp placement
• Business QR codes and barcodes

If the business meaning is specific, prefer the dedicated type rather than treating every image-based case as generic image.

3. How to Design the Four Core Field Attributes

At a minimum, every variable should have clear decisions for these four attributes:

• name
• key
• description
• required

1) name: the human-facing label

name determines:

• The label shown inside the document body
• The label shown in the form panel on the right

Recommendations:

• Use a name that business users understand immediately
• Avoid having multiple fields with exactly the same name but different meanings inside the same template

Good examples:

• Contract Name
• Party A Name
• Effective Date
• Approval Comment

Poor examples:

• Name 1
• Text Field
• Explanation Content

2) key: the stable program-facing identifier

In the current implementation, values are matched by key first and only fall back to id if key is missing. In production, do not rely on auto-generated id values. Always provide a stable key explicitly.

Recommended principles:

• One field should have one stable key
• Once a key is used externally, avoid renaming it casually
• Name keys by business meaning, not by UI wording

Recommended style:

contract_name
party_a_name
effective_date
approver_comment

Poor examples:

var_xxx
text1
fieldA

3) description: filling guidance and business context

description is a good place for:

• Explaining what the field means
• Explaining where the value should come from
• Providing filling guidance

Recommended examples:

• “Please enter the registered legal entity name exactly as shown on the business license”
• “Use the format YYYY-MM-DD”
• “If there is no additional explanation, this field may be left blank”

Do not pack all validation rules into description. If a rule can be expressed by the variable type or by validation rules, let the rule system handle it.

4) required: whether the field is mandatory

Whether a field should be required should be based on whether the business process can tolerate it being missing, not simply on whether the field is “usually filled”.

Recommended rule of thumb:

• If the document cannot be generated correctly without it, make it required
• If it is only a note or optional supplementary explanation, do not make it required

4. Value Shape Design Rules

Based on the current implementation, the following value shapes are recommended for different variable types.

Text / Number / Radio / Select

Recommended value types:

• String
• Number

Example:

{
  contract_amount: 12800.5,
  party_a_name: 'Example Technology Ltd.',
  contract_status: 'approved',
}

Multi-select checkbox

Checkbox values should be arrays.

Example:

{
  notice_channels: ['email', 'sms'],
}

If a non-array value is passed in, it will not be handled correctly as a multi-select field.

Date / Date Range

A single date should usually be passed as a single value. Date ranges and time ranges should usually be passed as arrays of length 2.

Example:

{
  effective_date: '2026-07-29',
  service_period: ['2026-08-01', '2027-07-31'],
}

If the field is a range but only one side is provided, it will typically be treated as an empty range.

Image-like Variables

Image-like variables support both direct URL strings and object values.

Recommended object shape:

{
  signature_image: {
    url: 'https://example.com/signature.png',
    name: 'Signature',
    size: 10240,
    type: 'image/png',
    width: 300,
    height: 120,
    content: null,
  },
}

The minimum requirement is that url must exist. Without url, the value is treated as empty.

Rich Text Variables

The current flow accepts the following as input for rich text variables:

• Non-empty strings
• Non-empty arrays
• Non-empty objects

That does not mean that any arbitrary content can be written into the document safely. If the content cannot be accepted by the current document model, the population flow will report it through onFillError.

Recommendations:

• Let only trusted programs generate rich text content
• Constrain the structure on the server side ahead of time
• Use it only where genuinely complex content is required

5. Field Design Best Practices

1) Use one data meaning for one business field

For example, if “contract amount” is a numeric field, keep it numeric everywhere. Do not model it as text in one template and number in another.

That makes it much easier for the backend to reuse one data-mapping strategy across templates.

2) Keep key stable over time

You can rename name, but do not casually rename key. Otherwise:

• Historical backfilling may stop working
• Programmatic population mappings may break
• Downstream saved data may become disconnected

3) If it can be enumerated, do not make it free text

Examples include approval result, gender, signed/not signed, payment method, department type, and similar fields. These should usually use option-based variables.

4) If it can be structured, do not push it all into rich text

If a field is fundamentally a date, amount, code, or final outcome, do not push it into a rich text variable just for the sake of flexibility.

5) Use rich text only for complex content blocks

Recommended places for rich text variables:

• Report explanation areas
• Server-generated table areas
• Clause block insertion areas

Do not push a large number of core business fields from the entire document into rich text.

6) In batch-generation templates, field granularity should be balanced

If fields are too coarse, programmatic reuse becomes harder. If fields are too granular, template maintenance and data passing become expensive.

Recommended principle:

• Split out fields that have genuinely independent data sources on the backend
• Keep text as fixed template body content when it always appears together and does not vary independently

6. Field Design for Batch Generation

If your goal is to batch-generate formal PDF or Word files, focus on the following:

• key values are stable and semantically clear
• Similar templates use consistent field naming
• Numbers, dates, and options use explicit types
• Keep rich text fields to a minimum and reserve them for truly complex content
• Draw a clear boundary between fixed body content and variable body content

When those conditions are met, the program side mainly needs to prepare variable data and can then reuse the same template to generate many different results reliably before passing them into the Word/PDF export flow.

7. When Field Design Should Be Refactored

If you start seeing the following symptoms, it usually means the template field design needs to be revisited:

• The backend always needs an extra conversion layer just to prepare values
• Different templates use different keys for the same business field
• Business users are frequently unsure where a certain field is supposed to be entered
• Programmatic population requires building many strings first and then pushing them into rich text
• Similar documents start drifting apart structurally after export

The earlier these issues are addressed in the template design phase, the more stable manual filling, programmatic population, export, and archiving become later on.