Errors and validation responses

Page contents:

Understanding validation results

Validation results are retrieved using:

GET /vet-provider/v1/{jurisdiction}/transaction-batch/{transactionBatchToken}/failed-validation-results

Validation results contain findings produced by the STARS validation framework and provide information that identify

• the affected resource

• the affected resource attributes

• related validation results generated by the same validation rule execution

• the scope of the validation failure.

Validation failures identified during request and schema validation are returned using Problem Details responses and are documented separately.

See also Problem Details

Validation result attributes

The following attributes are commonly used together when interpreting validation results

Complete validation result example

The following example shows a validation result containing the attributes most commonly used when interpreting a validation failure.

Resource identification

Every validation result relates to a specific resource.

Example:

Together, these values identify the resource that triggered the validation result.

Access path

Validation results identify the specific resource entity, attribute, or attributes that caused a validation rule to fail. These locations are identified using accessPath.

accessPath is returned in validation results:

• locate the affected data element(s)

• understand how a rule was evaluated

• identify affected child objects within collections

• highlight or navigate users directly to the affected attribute(s)

• apply targeted corrections to the submitted payload

An accessPath value uses JSONPath-RFC9535 notation to identify the resource attributes involved in the validation result.

Format

accessPath is an array of strings, where each entry represents a path to a resource attribute involved in the validation.

Example:

A validation result may contain one or more access paths depending on how the validation rule was evaluated.

Access path syntax

accessPath values use JSONPath notation to identify locations within a submitted resource.

Common patterns include:

Examples

Resource-level validation

"$" 

Identifies the resource as a whole.

Top-level attribute

"$.surveyAvailability" 

Identifies the surveyAvailability attribute.

Nested attribute

"$.permanentAddress.postcode" 

Identifies the postcode attribute within the permanentAddress object.

Child collection item

"$.locations[?@.locationUsageType=='Primary']" 

Identifies a specific item within the locations collection.

Each path:

• starts from the root of the resource ($)

• uses dot notation to navigate resource attributes

• may include multiple entries where a rule evaluates multiple resource attributes

Common patterns

1. Single‑attribute validation

When a rule evaluates a single resource attribute, accessPath contains one entry.

Interpretation

• The validation failure relates only to firstGivenName

• The value is either invalid, missing, or violates a constraint

• Correction should focus on this attribute only

2. Multi‑attribute (conditional) validation

When a rule depends on the combination of resource attributes, multiple paths are returned.

Interpretation

• The rule evaluates the relationship between these attributes

• The failure may not be isolated to a single attribute

• An attribute may be considered invalid due to its relationship with another attribute

3. Multiple validation results from a single rule execution

A rule execution may produce multiple validation results.

Each validation result will contain its own accessPath. When the results are produced by the same rule execution, they share a common validationGroupingId.

How to use accessPath

Locate the issue in your payload

Use each path to match the structure of the data you submitted:

$.firstGivenName points directly to the affected attribute.

Where a child collection is referenced, the path identifies the specific child object involved in the validation result.

Determine the scope of the problem

• Single path > isolated attribute issue

• Multiple path > conditional or cross‑attribute rule

• Repeated occurrences > potentially multiple resources or instances affected

Apply targeted corrections

When correcting data:

• Update the resource entity or resource attributes referenced by accessPath (unless the rule requires changes to related attributes)

• Use collection filters to identify affected child objects where applicable

• Re-submit the resource using the same UID

• Validate again to confirm resolution

Related validation result attributes

accessPath should be interpreted alongside:

Together, these attributes provide sufficient context to locate, understand, and resolve a validation failure.

Important considerations

• accessPath identifies where, not always why a validation failure occurred

• Always interpret accessPath together with the rule description and corrective action

• The same resource attribute may appear in different rules with different meanings

• For conditional rules, the logical relationship between attributes is important

• accessPath may identify a resource, a resource attribute, a nested attribute, or a child object within a collection

• Paths refer to the structure of the submitted payload, not necessarily the stored representation.

Validation grouping

A validationGroupingId identifies validation results produced by the same execution of a validation rule.

Validation results that share the same validationGroupingId should be reviewed together because resolving the issue may require considering multiple related resources or attributes.

For a single execution of a validation rule, each affected resource receives its own validation result; however, all related validation results share the same validationGroupingId.

Many validation rules produce a single validation result.

Some validation rules evaluate relationships between multiple resource attributes, child objects, or top-level resources. When this occurs, a single rule execution can produce multiple validation results.

All validation results produced by that rule execution share the same validationGroupingId.

This allows identification of validation results that are related and should be interpreted together rather than as independent failures.

A validation response may contain results from multiple validation rules. Each execution of a validation rule is assigned its own validationGroupingId.

Validation results that share the same validationGroupingId should be interpreted as belonging to the same rule execution.

Uniqueness of validation results

A validation result is uniquely identified by the combination of

• technicalRuleId

• validationGroupingId

• resourceType

• resourceUID

• dataSource

A single execution of a validation rule may therefore produce multiple Validation Results when multiple related resources participate in the validation.

Related validation result count

relatedValidationResultCount indicates how many validation results belong to the same validation group.

All validation results that share the same validationGroupingId contribute to the count. This helps in understaning the scope of a validation failure and identify whether additional related validation results should be reviewed.

Example:

In this example, two validation results belong to the same validation group.

Use this information to determine whether additional related validation results should be considered when resolving a validation failure.

Example 1 - single validation result

The example below shows a validation result produced by a rule execution that generated a single validation failure.

Interpretation

• One resource is involved

• One resource attribute is involved

• The rule execution produced a single validation result

• No related validation results exist

Example 2 - related validation results

The following example is illustrative and demonstrates how related validation results may be returned for a validation rule that evaluates multiple resources.

Validation result 1

Validation result 2

Interpretation

• Both validation results belong to the same validation rule execution

• The shared validationGroupingId identifies the relationship

• relatedValidationResultCount indicates that two validation results belong to the validation group

• Two different resources are involved

• Each validation result identifies the affected resource attributes using accessPath

dataSource

The dataSource attribute identifies the source of the data involved in a validation result.

Used to determine whether a validation failure relates to:

• data uploaded in the current transaction batch

• previously submitted data stored by STARS

Possible values are:

Example

dataSource can help distinguish whether a validation failure was introduced by the current upload or relates to previously submitted data.

Processing validation results

When processing validation failures:

1. Use resourceType and resourceUID to identify the affected resource

2. Use accessPath to identify the affected resource attributes

3. Use validationGroupingId to determine whether the validation result is related to other validation results

4. Use relatedValidationResultCount to understand the size of the validation group

5. Use dataSource to determine whether the failure relates to current or previously submitted data

6. Use the associated rule information and corrective action to resolve the issue

Summary

Validation results provide both resource-level and attribute-level context.

• resourceType and resourceUID identify the affected resource

• accessPath identifies the affected resource attributes

• validationGroupingId identifies a specific execution of a validation rule

• relatedValidationResultCount indicates how many validation results belong to that rule execution

• dataSource identifies the source of the data involved in the validation result

These attributes allow SMS suppliers to identify affected resources and resource attributes, understand the scope of a validation failure, and determine which validation results should be interpreted together.

Validation scenario - handling a single blocking validation failure

This scenario demonstrates how validation results attributes can be used in interpreting and solving a single blocking validation failure. The scenario utilises technical rule BRTS01180.