Search…
How to make a document definition
The document definition is the basis of every "file" within Valtimo. The document definition determines the data structure of the 'document' where all data of the file is stored.
For our document definitions we use JSON schema. We will discuss the most common situations within our implementations in our documentation. For other situations you can consult the complete documentation of JSON schema:
Each document definition has the following basic structure:
1
{
2
"$id": "process-name.schema",
3
"$schema": "http://json-schema.org/draft-07/schema#",
4
"title": "Process name",
5
"type": "object",
6
"properties": {
7
}
8
}
Copied!
"$id" is the name of the process as we specified it in DocumentDefinitionDeployedListener.
"$schema" is not required but is a good practice to use. This indicates that this file is a JSON schema and which version we are using.
"title" is the name of the process, the name we enter here will also be used as the name of the process in the Valtimo "file" menu.
Note: the name of the file is the name of the business process. Multiple BPMN process models can work within 1 business process. The name is usually a noun that indicates what is in the file. For example: "complaints", "orders" or "wage subsidies".
Usually the use of verbs is undesirable. For example: "Order processing" or "Request an event permit".
Within the "properties" we can now define our data structure with the following elements:

1. Booleans

1
"applicationReceived": {
2
"type": "boolean",
3
"description": "Application received?"
4
}
Copied!

2. Strings

1
"streetName": {
2
"type": "string",
3
"description": "Street name"
4
}
Copied!

3. Numbers

Numbers can only be floats. (there is also an "integer" type, but since Javascript has no integers, we only use "number" to avoid confusion).
1
"houseNumber": {
2
"type": "number",
3
"description": "House number"
4
}
Copied!

4. Objects

We can also use objects to give our data a good structure. In this example we have created an address object containing all components of an address. This ensures that in our implementation we can refer to, for example, adres.streetname or adresss.houseNumber. We place all data, that we can logically group together, in an object. This also has advantages when creating forms, which we will come back to later in the "Forms" chapter.
1
"adres": {
2
"type": "object",
3
"description": "Adres",
4
"properties": {
5
"streetName":{
6
"type": "string",
7
"description": "Street name"
8
},
9
"houseNumber": {
10
"type": "number",
11
"description": "House number"
12
}
13
"postalCode":{
14
"type": "string",
15
"description": "Postal code"
16
},
17
"city":{
18
"type": "string",
19
"description": "City"
20
},
21
}
22
}
Copied!

5. Arrays

We can also store data in an array, we usually do this by means of an array of objects.
In our forms we use a FormIO "Data Grid" to store data in an array. A "Data Grid" uses an array of objects. More information about this can be found in the explanation about "Data Grids".
Under "items" we indicate what kind of input we expect for this array. In this case we expect an object with the "name" and "age" key-value pairs.
1
"leeftijden": {
2
"type": "array",
3
"items": {
4
"type": "object",
5
"properties": {
6
"name": {
7
"type": "string",
8
"description": "Name"
9
},
10
"age": {
11
"type": "number",
12
"description": "Age"
13
}
14
}
15
}
16
}
Copied!

6. Definitions

Because we always want to avoid writing duplicate code, we can also use "definitions" for common data structures. These are a kind of classes that we define in one place and that we can refer to in several places.
We define the 'definitions' in the root of our schema object in the following way:
1
{
2
"$id": "process-name.schema",
3
"$schema": "http://json-schema.org/draft-07/schema#",
4
"title": "Process name",
5
"type": "object",
6
"properties": {
7
}
8
"definitions": {
9
}
10
}
Copied!
Suppose we have address data from a requester and a handler, then we can convert the address object we used earlier in this chapter into a "definition" and then use it for both the requester and the handler.
1
"definitions": {
2
"address": {
3
"type": "object",
4
"description": "Address",
5
"properties": {
6
"streetName":{
7
"type": "string",
8
"description": "Street name"
9
},
10
"houseNumber": {
11
"type": "number",
12
"description": "House number"
13
}
14
"postalCode":{
15
"type": "string",
16
"description": "Postal code"
17
},
18
"city":{
19
"type": "string",
20
"description": "City"
21
},
22
}
23
}
24
}
Copied!
Now we can use this "definition" for the requester and handler with the $ref property.
1
"applicant": {
2
"type": "object"
3
"description": "Applicant"
4
"properties": {
5
"address": {
6
"type": "object"
7
"$ref": "#/definitions/address"
8
}
9
}
10
}
11
"handler": {
12
"type": "object"
13
"description": "Handler"
14
"properties": {
15
"address": {
16
"type": "object"
17
"$ref": "#/definitions/address"
18
}
19
}
20
}
Copied!
1
{
2
"$id": "process-name.schema",
3
"$schema": "http://json-schema.org/draft-07/schema#",
4
"title": "Process name",
5
"type": "object",
6
"properties": {
7
"applicant": {
8
"type": "object"
9
"description": "Applicant"
10
"properties": {
11
"address": {
12
"type": "object"
13
"$ref": "#/definitions/address"
14
}
15
}
16
}
17
"handler": {
18
"type": "object"
19
"description": "Handler"
20
"properties": {
21
"address": {
22
"type": "object"
23
"$ref": "#/definitions/address"
24
}
25
}
26
}
27
}
28
"definitions": {
29
"address": {
30
"type": "object",
31
"description": "Address",
32
"properties": {
33
"streetName":{
34
"type": "string",
35
"description": "Street name"
36
},
37
"houseNumber": {
38
"type": "number",
39
"description": "House number"
40
}
41
"postalCode":{
42
"type": "string",
43
"description": "Postal code"
44
},
45
"city":{
46
"type": "string",
47
"description": "City"
48
},
49
}
50
}
51
}
52
}
Copied!

7. Validation

There are also a number of ways we can validate our data. By default, a validation will already take place based on our data types. For example, if we have defined "houseNumber" as "number", we cannot store a string.
We will discuss the most common validation options here. For more options you can check the JSON schema documentation: https://json-schema.org/understanding-json-schema/index.html
additionalProperties
Available for data type: object
To ensure we can only store data that we have defined, we can add "additionalProperties”: false to objects. Since our JSON schema itself is also an object, we can also apply it to the root of the schema.
1
{
2
"$id": "process-name.schema",
3
"$schema": "http://json-schema.org/draft-07/schema#",
4
"title": "Process name",
5
"type": "object",
6
"additionalProperties”: false,
7
"properties": {
8
}
9
}
Copied!
additionalProperties only applies to the object you add this property to, not the children of this object.
After adding or removing additionalProperties, the database must be cleared or the validation will not be applied.
minLength
Available for data type: string
Minimum length of a string.
1
"name": {
2
"type": "string",
3
"description": "Name",
4
"minLength": 2
5
}
Copied!
maxLength
Available for data type: string
Maximum length of a string.
1
"name": {
2
"type": "string",
3
"description": "Name",
4
"maxLength": 32
5
}
Copied!
pattern
Available for data type: string
Validation based on a regular expression.
1
"postalCode": {
2
"type": "string",
3
"description": "Postal code",
4
"pattern": "^\\d{4}\\s?\\w{2}quot;
5
},
Copied!
Een handige tool voor het schrijven van regular expressions: https://regexr.com
minimum
Available for data type: number
Minimum value of the number.
1
"houseNumber": {
2
"type": "number",
3
"description": "House number",
4
"minimum": 200
5
}
Copied!
maximum
Available for data type: number
Maximum value of the number.
1
"houseNumber": {
2
"type": "number",
3
"description": "House number",
4
"maximum": 600
5
}
Copied!
Last modified 2mo ago