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

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.

« Creating a definition dataset Creating a document definition Messages and translations »