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

You can add custom messages to be used in the user interface for any field or type. Messages are specified under the messages key as a map of message code and message entries.

A label can also be provided for every field definition.

Example YAML document definition with custom messages

document-definition:
  name: sample-document
  types:
    - id: telephone-number
      base-type: string
      messages: (1)
        tooltip: "Enter your telephone number"
        help: "+32 xxxx/xx.xx.xx"
  content:
    - id: name
      type: string
      messages: (1)
        description: "Your personal name"
    - id: telephone
      label: "Telephone number" (2)
      type: telephone-number
      messages: (3)
        help: "0032 xxxx/xx.xx.xx"

1	You can define a `messages` block on both a type or a content field definition.
2	This is the label used to display as the column heading in a list view or the label of the form.
3	A message defined on a content field will replace a message with the same code on the type definition. In this example, the `help` code from the base type will be overwritten and contain `0032 xxxx/xx.xx.xx`.

Any message code can be localized by suffixing the locale code.

Example YAML document definition with custom messages and locales

document-definition:
  name: sample-document
  content:
    - id: name
      type: string
      messages: (1)
        description: "Your personal name" (1)
        description_en_: "Your personal name in English" (2)
        description_ja_JP_: "あなたの個人的な名前" (3)
        description_no_NO_NY: "Ditt personlige navn"  (4)

1	The default description, used when no matching locale was found.
2	The description for all English speaking countries (Australia, Candara, India, Ireland, Malta, …).
3	The description for Japan.
4	The description for Norvegian Norsk, a variant of standard Norvegian Bokmål.

Default message codes

The following message codes can be configured:

description: On a form, this shows a description message above the control for that field.
help: On a form, this shows a help text below the control for that field.
tooltip: On a form, this is the text behind a tooltip (question mark) icon next to the field label.
placeholder: For a textbox form control, this is the placeholder message shown if the textbox is empty.