> For the complete documentation index, see [llms.txt](https://docs.dynalogic.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.dynalogic.com/birds-document-warehouse-product-overview/setup-and-configuration/fields.md).

# Fields

Fields allow to add extra meta data to a document in a structured way.

A field exists of:

| Property              | Details                                                                                                           |
| --------------------- | ----------------------------------------------------------------------------------------------------------------- |
| Code                  | Unique field identifier.                                                                                          |
| Label                 | Field label.                                                                                                      |
| Required              | Whether a value is required.                                                                                      |
| Read only             | Whether the field is read only.                                                                                   |
| Type                  | Text, Number, Date, Tag, User, Time Stamp, or Time Span (duration). See the special behavior of tag fields below. |
| Row amount            | Creates multiple lines; only for tag fields.                                                                      |
| Default value         | Optional.                                                                                                         |
| Validation expression | Optional regular expression.                                                                                      |

You can see, modify and create new fields in the Fields tab of the configuration page.

Just like tags, fields have a code, which must be unique.

Fields can be of type date, text, number or user.

The tag field is a special kind. It acts as a filter on all the tags linked to the document.

An example: a document has many tags, and you want to hightlight those that are referring to customers, then you can add a field of type tag, and select a tag that is the parent of all the customers. This will then result in a list of selected customers.

This also helps when you want to add a customer, if you would just try to add the tag in the general tag section at the top, there could be many other tag suggestions like projects for the customer etcetera. But when you start typing the name of a tag in a tag field, only tags that are “descendant” of the customer tag will be suggested (and allowed).

{% hint style="info" %}
It is not possible to set validation expressions on tag fields, or restrict the possible tags that could be added here, since it is always possible to add any tag to a document.
{% endhint %}

## Create a field

When you want to create a field, you should know these things:

* The unique code for the field
* The type of data
* In case of a tag field: the parent tag

If you have that information, you can proceed by:

{% stepper %}
{% step %}

### Open the Fields tab

Navigate to the configuration page and select the “Fields” tab.
{% endstep %}

{% step %}

### Add the field

Click on the “+” button at the top of the field and enter the pre-requisit information.
{% endstep %}

{% step %}

### Save and complete the settings

Save the field, and make any other changes (default value, validation …).

![](https://1567270722-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbMdBZV3cNP56k0aYYCI6%2Fuploads%2Fgit-blob-0d165233b20ba22604b5861c58c551d16bf49a08%2Fta_create_a_field.jpg?alt=media)
{% endstep %}
{% endstepper %}

## Edit a field

To edit a field, navigate to the configuration page, select the “Fields” tab, and find the field you want to modify in the list. Select that field and you can modify several of it’s properties.

{% hint style="warning" %}
You cannot change the type, or the validation expression of the field after it is used by at least one document.
{% endhint %}

<figure><img src="https://1567270722-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbMdBZV3cNP56k0aYYCI6%2Fuploads%2Fgit-blob-8651f34a6d0bdecf56fa61eb3f26015ad61316ee%2Fimage%20(361).png?alt=media" alt=""><figcaption></figcaption></figure>

## General options

**Required**

The ‘Required’ toggle on a field defines if the field is expected to have a value on each document. A ‘\*’ will appear next to the field indicating this to the user. When a document has a required field with no value, it will be marked as ‘Incomplete’.

![](https://1567270722-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbMdBZV3cNP56k0aYYCI6%2Fuploads%2Fgit-blob-3d3f59d352166f183055ef2188fdb5a31ae00e59%2Fimage%20\(368\).png?alt=media)

**Read only**

The ‘Read only’ toggle will disable the field when turned on, so that it can only be edited through the API. This could be useful if you want the field to be only informational, or when it should only be edited by external processes that use the API to edit the metadata of the document.

The tag field in this case is an exception, as tags can still be added/removed from the ‘Tags’ input on top of the document detail form, thus making users able to edit the tag field even if it read-only.

Read only fields can be added or removed by users if the user role allows it.

## Details

**Validation Expression**

A validation expression is a regular expression that must match the value of field. IF the validation fails, the value cannot be saved. If a validation is configured, it is also possible to define a “validation message” which can be shown to a user if the validation fails.

For example: on a number you could add this regular expression: **$\d?\d^** this would allow to add minimum 1 digit, and maximum two digits without a coma or decimal separator. Basically allowing you to enter a positive number in the range: \[0, 99].

Remark: the regular expression is always executed on a string, and it is serialized using the invariant culture.

**Format**

Some field types like Time Stamps and Time Spans, can have a format applied to them.\
This format parameter will influence how those fields are displayed to the user, but note that different users can still see differently formatted values, based on the language (culture) they are using.

{% tabs %}
{% tab title="Time Stamp" %}
The format is passed in as a single text string, that can have following codes:

**yyyy** for the full year with 4 digits, or **yy** for only the last 2 digits.\
**MMM** for the month fully spelled out, **MMM** for the abrivated name of the momnth, **MM** for 2 digits months, M for single digit month. (some cultures always use 2 digits)\
**dddd** for the day of the month fully spelled out, **ddd** for the abreviated day of the month, **dd** for 2 digit days, **d** for single digit day.

**H** to include the hours, in 24h format, single digit.\
**HH** to include the hour in 24h format, double digit.\
**h** to include the hour in 12h format single digit\
**hh** 12h format, double digit\
**s** to include seconds in the time part.\
**t** to add am/pm (when in 24h mode)\
**z** to add time zone information

\ <br>
{% endtab %}

{% tab title="Time span" %}
**d** for adding the number of days\
**hh**, or **h** hours (12h clock)\
**HH**, or **H** for hous (24h clock)\
**mm**, or **m** for minutes\
**ss**, or **s** for seconds\
**f**, **ff** or **fff** for fractional seconds\
**a** for the A.M / P.M. indicator\
\
You can use : and . for separaters between each segment.
{% endtab %}
{% endtabs %}

**About**

Any field can be added to any document at most once.

If a field is part of the selected template, it cannot be removed. Otherwise it can be removed.

(Note that a template can always be changed, so there is no way to prevent the user to remove a field.)

**Remarks**

The type of a field cannot be changed once the field is created (and used) by at least one document.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.dynalogic.com/birds-document-warehouse-product-overview/setup-and-configuration/fields.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
