Validation of Mapping Type Instance Values

This articles below describe the detailed validation rules that the Universal Mapping Assistant SuiteApp applies when installing a mapping type instance:

General Validation Rules
Installer Validation Failures
Built-In GL Accounts SAF-T 2.0 Validation Rules
Built-In Methods of Payment Validation Rules
Built-In Units of Measure Validation Rules
Built-In Tax Codes Validation Rules
Troubleshooting Guidance

General Validation Rules

The following general rules apply to a mapping type instance installation independently of the specific mapping type:

values must be an object.
configuration is required. Its format depends on the selected mapping type.
Every target value entry under values must define a non-empty uid string.
If a mapping type uses nested value objects under values, the same UID rule applies recursively there as well.
uid values must be unique across the whole values tree, not only inside one array.
suggester is optional, but if it is provided, it must resolve to a valid module.
Business fields such as code, name, and description are not a stable identity.

Installer Validation Failures

Validation failures include structured context that helps identify which validation layer failed.

Generic mapping type instance validation failures use stage=<validator stage>; detail=<string message>.
Target-controller validation failures use stage=validateValues; target=<controller id>; detail=<json payload>.

The exact wording of the error message can evolve as validators change. Use stage, target, and detail to identify the failing validator and the invalid value.

Example: Missing UID

            Error: The specified Mapping Type Instance is not valid. stage=validateValues; detail=uid is mandatory for all mapping type instance value entries (path: values.groupingCodes[0].uid)

Example: Target validation detail

            {
    "stage": "GroupingCodeValidator.checkDuplicateCodes",
    "entity": "groupingCode",
    "reason": "duplicate-code",
    "uid": "CODE_DEV",
    "code": "1000",
    "category": "CAT_FIXED_ASSETS"
}

Built-In GL Accounts SAF-T 2.0 Validation Rules

For the built-in GL Accounts SAF-T 2.0 mapping type:

Every grouping category must define a non-empty uid string.
Every grouping code must define a non-empty uid string.
groupingCodes[].category must reference a category UID that exists in the same payload.
Duplicate grouping category UIDs are invalid.
Duplicate grouping code UIDs are invalid.
Duplicate grouping business codes are invalid.
Empty categories are invalid.

For more information about the built-in GL Accounts SAF-T 2.0 payload shape, see Available Mapping Types.

Built-In Methods of Payment Validation Rules

For the built-in Methods of Payment mapping type:

Every payment method must define a non-empty uid string.
Duplicate payment method UIDs are invalid.
Duplicate payment method business codes are invalid.

For more information about the built-in Methods of Payment payload shape, see Available Mapping Types.

Built-In Units of Measure Validation Rules

For the built-in Units of Measure mapping type:

Every unitsOfMeasure[] entry must define a non-empty uid.
Every unitsOfMeasure[] entry must define a non-empty string code.
Duplicate units of measure UIDs are invalid.
Duplicate units of measure business codes are invalid.
name and description are optional. If provided, they must be strings.

For more information about the built-in Units of Measure payload shape, see Available Mapping Types.

Built-In Tax Codes Validation Rules

For the built-in Tax Codes mapping type:

configuration.countries must be a non-empty array.
Every configuration.countries[] entry must be a non-empty string.
values.countryTaxCodes must be an array.
Every values.countryTaxCodes[] entry must define a non-empty string uid.
Every values.countryTaxCodes[] entry must define a non-empty string code.
Duplicate country tax code UIDs are invalid.
Duplicate country tax code business codes are invalid.

name and description are display fields for the installed country tax codes and are optional in the accepted payload shape.

For more information about the built-in Tax Codes payload shape, see Available Mapping Types.

Troubleshooting Guidance

If the failure does not mention a target controller, start by checking the generic mapping type instance shape.
If the failure includes target, inspect the values managed by that controller first.
If the failure includes a structured detail payload, use fields such as reason, uid, code, and category to identify the invalid entry.