REST integration — Schemas and mapping

Not yet checked on the product

This chapter was written from the product's source code and has not yet been checked by a person on a running Cogneris. If what you see on screen differs, the screen is right — please tell your Cogneris contact so the chapter can be corrected.

Three tabs of the REST integration describe the data: Schemas says what the request body and the answer look like and what the phase receives; Request mapping builds the body from the process; Response mapping translates the answer into the phase's data. Both mappings (the de-para) are lists of rules: each rule reads a source, applies transforms in order and writes a target.

Content status	From source; not observed (workflow-fe f88c5c1, workflow-be 6703373, 2026-10-22)

Schemas

Field	What it does	Required	Format / values	Default	Validation messages
Request schema	Describes the request body. Its fields become the targets of the Request mapping, and before every call the body is validated against it. Shown only for POST, PUT and PATCH; for GET and DELETE: … requests have no body, so there is no request schema or request mapping.	No	A JSON Schema (draft-07 or 2020-12) describing an object or an array	—	Invalid JSON: … · Not a valid schema: describe an object (type "object") or an array (type "array").
Response schema	Describes the answer. Its fields are offered as sources of the Response mapping and as fields of the Result rules, and a success answer is validated against it.	No	Same as above	—	Same as above
Input example (JSON)	An example of what this phase receives from the previous one. It feeds the source paths of the mapping and the test; it is never used at run time. It may also carry the process data under $form, $process, $doc and $run, for example { "$form": { "nif": "PT500000000" } }; their keys are then offered as sources and the Test uses their values.	No	JSON	—	Invalid JSON: …

Schema input

Each schema has two modes, chosen under Schema:

• JSON Schema — Paste the JSON Schema. The schema is applied as soon as the text is valid; clearing the text removes the schema.
• Example → infer — Paste an example JSON, then select Infer schema. The editor writes a schema from the example, switches back to JSON Schema and shows Schema inferred from the example. Review it before saving.

How a schema is inferred from an example:

In the example	In the schema
Text	string
A whole number, a decimal number	integer, number (both seen in the same place: number)
true / false, null	boolean, null
An object	object with one property per key
A list	array; the items of the list are merged into one item schema, so an item that has a key another lacks still contributes it
Different types in the same place	A list of types, for example string and null

An example cannot prove that a field is mandatory, so an inferred schema marks nothing as required. Add required by hand where a field must always be present: required fields of the Request schema must then have a rule.

The service limits a schema to 256 KB, 64 levels and 20000 nodes, and does not support patternProperties.

Load an example from a run

Load from a run (reads Loading runs…) lists up to five recent outputs of the phase that feeds this one, as Use run example … … with the number and the time. Picking one fills Input example (JSON) and shows This example came from a real run and is used only while editing: it is not saved in the workflow. The process data of those runs offers its keys as sources; its values are masked by the service.

Message	Cause
Save the workflow before loading an example from a run.	The workflow was never saved; the button is disabled
No recent run reached this phase yet.	No process has completed the previous phase yet
Loading from a run is not available in this environment yet.	The service does not offer it here
Could not load the recent runs.	Any other failure; try again

Request mapping

Builds the request body: the target is the request schema, the source is the input example. Only for POST, PUT and PATCH.

With a request schema, the tab shows the schema as a tree (Destination fields): each field with its name, its type, Required when the schema requires it, and No rule when nothing writes it yet. Fields that hold a value, and lists (shown with []), can be mapped:

Button	What happens	Reversible?
Map	Creates a rule for the field and opens it	Yes — Remove
Edit / Close	Opens or closes the rule's form	—
Remove	Deletes the rule	No

A mapped field shows Source: … · transforms: … ((no source) when it has none). A rule whose target is not in the schema is listed under Rules without a matching schema field, with an editable Target path.

Without a request schema, rules are a plain list: Add rule adds one with an empty Target path, and each has Edit and Remove.

At the top, No issues found. or Issues to fix: … counts the errors of all the rules. Each rule's form shows its own messages; they are listed in Messages.

The rule form

Field	What it does	Required	Format / values	Default	Validation messages
Target path	Where the value is written in the body (or in data for a response rule). Set by the schema tree, or typed for a rule without a schema field.	Yes	Dotted path: customer.name; items[0].code for a fixed position; items[] (last segment only) for a list rule	—	The rule has no target path. · Target "…" does not exist in the schema.
Source	Where the value is read. See Sources.	Yes, unless the first transform is constant, concat or coalesce	A path, or a reserved source	—	A source is required unless the first transform is constant, concat or coalesce. · Source "…" was not found in the sample. (a warning: the rule still works)
Transforms	Applied in order to the value read from the source — see Transforms	No	Add transform › Choose a type; per transform: Type, Move up, Move down, Remove transform	No transforms: the value is copied as is.	Per transform, below
Item rules for …	For a list target (ending in []): rules applied to each item of the source list, with paths relative to the item. $ alone is the item itself. Lists can be nested up to 3 levels.	No	Rules, as above; sources inside are relative to the item	—	Item rules only apply to array targets (ending in []). · Arrays can be nested up to 3 levels.

Every required field needs a rule. A field the schema requires, inside an object that is required or that you map, must be the target of a rule: Required field "…" has no rule.

How rules are applied

• Rules run in order. Each reads its source, applies its transforms and writes the target, creating the objects on the way.
• When the value is missing at the end — the source does not exist, a regex_extract did not match, a concat found nothing — the target is not written. Add a default transform to write something instead.
• A value of null produced on purpose (by constant, default, lookup or the source itself) is written, as null.
• Two rules may write the same target: the later one replaces the earlier one when it produces a value. The VIES preset uses this to fill vies.status from two different fields of the answer.
• A list rule needs a source and a target that both end in [], and takes no transforms: without item rules it copies the list; with item rules it builds one new item per source item.
• At most 500 rules per mapping, paths of up to 512 characters and 32 segments, fixed positions up to 10000.

Response mapping

Translates the response into the phase output under data: the source is the response schema, the target is a free path. Without rules, data receives the raw response.

There is no target schema on this side: rules are a plain list with Target path, Add rule, Edit and Remove. The sources offered are the fields of the Response schema. Besides paths in the answer, a response rule may read what was sent, with $request. followed by a path: the body built by the Request mapping, or, for GET and DELETE, a path or query parameter by name. The VIES preset uses $request.countryCode to return the country it asked about. No other reserved source is allowed here: Source "…" is not valid here: a response rule can only read what was sent, with $request.….

Order of work on a success answer: the Rules on the response body of the Result tab first, then the Response schema, then the response mapping.

Sources

Source	Reads	Where it is allowed
A path such as customer.taxId, items[0].code, items[]	The input of the phase — the output of the previous phase — as in the Input example. Inside item rules, a path relative to the current item.	Everywhere
$form. + key	An answer of the portal form, with dotted keys for nested answers	Top-level request rules, path and query parameters
$process. + key	Process metadata, for example $process.identifier, $process.requester.name, $process.today	Same
$doc. + document type + . + field	That field of the first document of that type that has it	Same
$doc. + document type + []. + field	The list of that field over every document of that type	Same
$run.id, $run.workflowId, $run.tenantId	Run metadata, with no personal data	Same
$request. + path	What the phase sent	Response rules only

Values read from $form, $process, $doc and $run are text. A key that is absent resolves to nothing, so a default transform applies. Document types are your extraction templates' names; the list offers their fields. They are refused inside item rules — Source "…" reads the run ($form, $process, $doc, $run) and can only be used in top-level rules, not in item rules. — and a malformed one is refused everywhere: Source "…" is not valid: use $form.…, $process.…, $doc.….…, $doc.…[].… or $run.id, $run.workflowId, $run.tenantId.

Transforms

The transform list is closed: the Type list shows the sixteen types by name — for example Extract with regex for regex_extract, First non-empty value for coalesce, Look up in table for lookup. The headings below use the technical name the configuration stores. Transforms run in order, each on the result of the one before.

Most transforms leave a missing or null value as it is — only constant, default, concat and coalesce produce a value from nothing. Put default last to fill what is still missing.

A transform that fails at run time stops the mapping: the process goes to Error with the kind request_schema (request side, path and query parameters) or response_schema (response side). The message, in English, names the rule, the transform and the value, cut at 100 characters — for example Rule 'customer.document': to_number failed for the value 'abc'.

constant — fixed value

Replaces the value with a fixed one, whatever was read. As the first transform, the rule needs no source.

Parameter	Format
Value	Text, number, true, false or null. Wrap in quotes to force text. 12 is the number 12, "12" the text 12, abc the text abc.

Example: any input → Value "BR" → "BR". With Value null the target is written as null.

default — value when empty

Uses Value (same format as constant) when the value is missing, null or empty text; otherwise keeps it.

Example: missing → Value 0 → 0; "abc" → "abc".

trim, upper, lower

Remove the spaces at both ends, or change to capitals or small letters. They act on text only; any other value is kept as it is. No parameters.

Example: " pt " → trim → "pt" → upper → "PT".

digits_only

Keeps only the digits 0–9 of a text or a number; the result is text. No parameters. Fails on an object, a list or a true/false value.

Example: "12.345.678/0001-90" → "12345678000190".

alnum_only

Keeps only letters (of any alphabet) and digits of a text. Other values are kept as they are. No parameters.

Example: "PT 500-000-000" → "PT500000000".

regex_extract — regular expression

Returns one group of the first match of a regular expression. Returns the chosen group. With no match the value is empty, so a following default can fill it. A number is matched as its text.

Parameter	Format	Default
Regular expression (up to 256 characters)	A .NET regular expression	—
Capture group (0 = whole match)	A whole number from 0 to the number of groups in the expression	1
Ignore upper/lower case	On or off	Off

Example: "PT500000000", expression ^([A-Z][A-Z]), group 1 → "PT". With no match → missing.

Errors: regex_extract needs a pattern of 1 to 256 characters. · regex_extract: the group must be a whole number from 0 up to the number of groups in the pattern. · an expression the service cannot compile is refused at publication · a match that takes longer than 100 ms fails at run time.

concat — concatenation

Joins the values of several source paths with a separator. It ignores the value read by the rule, so as the first transform the rule needs no source. Missing and null values are skipped; numbers and true/false are joined as text; an object or a list fails. When every source is missing, the result is missing.

Parameter	Format	Default
Source paths (one per line)	Paths, as in Source; at the top level, reserved sources are allowed	—
Separator	Text, may be empty	empty

Example: firstName = "Ana", lastName = "Silva", separator a space → "Ana Silva".

Error: concat needs at least one source path.

coalesce — first non-empty

Uses the first path whose value is neither empty nor null. Like concat, it ignores the value read by the rule. When every path is missing, null or empty text, the result is missing.

Parameter	Format
Source paths (one per line)	Paths, as in Source

Example: mobile empty, phone = "+351 210 000 000" → "+351 210 000 000".

Error: coalesce needs at least one source path.

date_format — date with format and time zone

Reads a date in one format and writes it in another.

Parameter	Format	Default
Input format (iso or pattern)	iso for ISO 8601, or a .NET date pattern such as dd/MM/yyyy	iso
Output format (iso or pattern)	iso (written as yyyy-MM-ddTHH:mm:ssK) or a pattern	iso
Time zone (optional)	A time zone name such as Europe/Lisbon	none

With a time zone, a date that carries no offset is read as a time in that zone, and a date that carries one is converted to it.

Examples: "15/03/2024", input dd/MM/yyyy, output yyyy-MM-dd → "2024-03-15". "2024-03-15T13:45:30Z", input iso, output dd/MM/yyyy HH:mm, time zone Europe/Lisbon → "15/03/2024 13:45".

Errors: date_format needs both the input and output formats. · a pattern or time zone the service does not recognise is refused at publication · a value that is not text, or that does not match the input format, fails at run time.

number_format — number with separator and decimals

Reads a number written with a given decimal separator, with or without thousands separators, and returns a JSON number.

Parameter	Format	Default
Decimal separator of the input	. or ,. The other sign is taken as the thousands separator.	,
Decimal places (optional)	Whole number 0–10: rounds, halves away from zero	none (no rounding)

Examples: "1.234,56" with , → 1234.56; with 1 decimal place → 1234.6. "1,234.5" with . → 1234.5. A number is kept (and rounded if asked).

Errors: The decimal separator must be "." or ",". · a text that is not a number in that format fails at run time.

to_string, to_number

• to_string writes a number or true/false as text; text is kept; an object or a list fails. Example: 123 → "123".
• to_number reads text as a number with . as the decimal separator; a number is kept; anything else fails. Example: "42.5" → 42.5. For "42,5" use number_format.

No parameters.

to_boolean — boolean with true and false values

Turns text or a number into true or false, comparing without regard to case. A value already true/false is kept.

Parameter	Format	Default in the editor
True values (comma-separated)	Texts	true, 1, sim, s, yes, y
False values (comma-separated)	Texts	false, 0, nao, não, n, no

Example: true values sim, yes, 1, false values não, no, 0: "Sim" → true, 0 → false, "talvez" → fails.

Errors: to_boolean needs at least one true value and one false value. · the same text in both lists is refused at publication · a value in neither list fails at run time.

lookup — value table with fallback

Replaces a value by the one a table gives for it. The comparison is exact (case matters); a number or true/false is looked up as its text.

Parameter	Format	Default
Value table	Pairs From value → To value; Add pair, Remove pair. To value is text.	—
When the value is not in the table	Keep the original value, Use null, Raise an error, Use a fixed value	Keep the original value
Fixed value	With Use a fixed value: the value to use, in the format of constant	—

Example: table M → Male, F → Female, fallback Use a fixed value "Unknown": "F" → "Female", "X" → "Unknown". With Raise an error, "X" fails.

Errors: lookup needs at least one entry in the table. · The lookup fallback is not valid. · a value not in the table with Raise an error, or an object or a list, fails at run time.

Other messages

Unknown transform "…". appears when a stored configuration names a type that does not exist; the transform is shown but cannot be edited. Remove it.

Related

• REST integration
• Request — path and query parameters use the same sources and transforms
• Result, Test and Publication
• Messages

---

Last reviewed 2026-10-22 · Version 1.0.0 · Owner: product-documentation