Creating a document definition

Defining fields

A dynamic document consists of a number of fields with corresponding values. A dynamic document definition holds all the metadata of those fields, it is in turn comprised of a number of field definitions.

A single field definition at minimum defines a unique id for that field, as well as a field type. The id identifies the field. The type determines how the field will be stored and treated in code (see dynamic field types).

A field id must be unique in the scope of its parent (usually the document itself or a fieldset). The field id will be used to build a fully qualified, unique path to that field in a document.

Example field id and path
document-definition:
  name: sample-document
  content:
    - id: name (1)
      type: string
    - id: address (2)
      type: fieldset
      fields:
      - id: street (3)
        type: string
      - id: number (4)
        type: number
1 top-level field with id name has path name
2 top-level field with id address has path address
3 fieldset member with id street has path address.street
4 fieldset member with id number has path address.number

Provide default values and formulas

A default value or formula can be set on a field by specifying it on the dynamic document definition. Default values specified on content will always override the default values specified on a type.

Setting a default value in combination with a default formula on the same field is not allowed.

Extensive example of default values on a field
document-definition:
  name: workspace-test
  types:
  - base-type: number
    id: age-field
    default:
      value: 1
  content:
  - type: number
    id: telephone
    default:
      value: 123456789 (1)
  - type: number
    id: prize4
    formula: "1+4"
    default: ~ (2)
  - type: fieldset
    id: address-and-city
    fields:
    - type: string
      id: city
      default:
        value: city
  - type: age-field
    id: age
    default:
      value: 50 (3)
  - type: age-field
    id: age2 (4)
1 field has a default value of 123456789
2 field has no default value or formula
3 field has a default value of 50
4 field has a default value of 1

When specifying a formula on a field it will automatically use that formula as the default for that field. You can explicitly reset the default by setting it to null (~ in yaml).

Extensive example of default formulas on a field
document-definition:
  name: workspace-test
  content:
  - type: number
    id: prize1
    default:
      formula: "1+4" (1)
  - type: number
    id: prize2
    formula: "1+4" (2)
  - type: number
    id: prize3
    formula: "1+4"
    default:
      value: ~ (3)
1 field has a default value of 5
2 field has a default value of 5
3 field has no default set

Add field validators

A document field can have any number of validators attached to it. When a document is validated, every field will be checked against its validators to determine if the field value is valid.

Validators are specified under the validators key as a list of configuration settings. Configuration settings can either be a single String value identifying the validator, or a map with String keys.

The default administration UI will not allow saving an invalid document. However, document validation is a separate step that needs to be performed manually.

See the chapter on validating a document in code for more information.
Example YAML document definition with field validators
document-definition:
  name: sample-document
  types:
    - id: telephone-number
      base-type: number
      validators: (1)
        - my-custom-pattern-validator: "+xxxx/xx.xx.xx"
  content:
    - id: name
      type: string
      validators:  (1)
       - required
    - id: telephone
      type: telephone-number
      validators:  (2)
       - required
1 Validators can be added on both type and field definitions.
2 The set of validators defined on type and field definition will be merged. For our telephone field, both my-custom-pattern-validator and required would be applied.

There are separate pages with the list of the available validators and information on creating a custom validator.

Configure custom messages and labels

See the separate section on document messages, labels and translations.