Skip to main content

6.6 Connectivity Editor – Semantic Validation Rules

Overview​

The Connectivity Editor validates new datapoints and connectors at registration time.

This document describes the custom semantic validation rules applied during registration. These rules validate references, expressions, and connectivity logic beyond basic structural checks.

Important:
Validation errors do not block submission.

Datapoints and connectors that violate the semantic validation rules described in this document can still be submitted and stored. Validation results are provided to give early feedback, improve quality, and highlight potential runtime issues, but they are non-blocking by design.

Note:
Structural validation, for example required fields, data types, and presence of ref, is handled separately and is not covered in this document.


Validation Scope​

ArtifactCustom validation applied
ConnectorStructure, reference uniqueness, reference existence, expression roots, element existence
WorkflowWorkflow schema validation
SchemaBase schema validation, additional-properties validation
DatapointNone — no datapoint-specific rules are implemented

Every artifact additionally goes through generic JSON and JSONata parsing, and through schema validation where a schema applies.

A datapoint is not semantically validated

There are currently no datapoint-specific validation rules. A datapoint's expressions are parsed as JSONata but are not checked against the namespaces that a datapoint can actually resolve, so an expression such as ${ref.something} or ${root.value} in a datapoint definition is stored without any warning and silently resolves to nothing at execution time.

Only input and env exist in a datapoint's resolution context — see Namespaces by scope. Getting this right is on you; the editor will not catch it.


Connector Validation Rules​

A connector defines how elements are wired together and how parameters reference inputs, outputs, and other connector elements.

Connectors use a strict semantic validation model. All references, expression roots, and cross-element accesses must be fully resolvable at registration time.


1. Connector Element ref Must Be Unique​

Each connector element must define a unique ref value.

Uniqueness is validated; the naming convention is not

ref is an ordinary string in the metamodel, with no pattern constraint, so the editor does not check its spelling. A name containing a dash is accepted here and then fails silently when a placeholder reads it — see Naming Convention Guidelines. The examples on this page use camelCase for that reason.

Invalid example:

[
{
"ref": "duplicateRef",
"element": "adder-endpoint"
},
{
"ref": "duplicateRef",
"element": "adder-endpoint"
}
]

Error:

[DUPLICATE_REF]
Duplicate ref 'duplicateRef' found. Each ref must be unique.

2. Referenced Elements Must Exist​

The element field must reference a registered and valid element.

Invalid example:

{
"ref": "invalidElement",
"element": "adder-endpoint-bla"
}

Error:

[INVALID_CONNECTOR_ELEMENT]
'adder-endpoint-bla' does not exist

Expression Validation in Connector Parameters​

Parameter values may contain expressions using the ${ ... } syntax.

Expressions are parsed and validated; they are not treated as free text.


Allowed Expression Roots​

Dots (.) are only allowed after the following roots:

RootDescription
refDocumented output of another connector element
responseFull HTTP response of another connector element
inputThe current execution payload
rootThe payload the connector was invoked with
paramsThe parameters of the current connector element
outputAccepted by the validator, but only resolvable in an output transformer
env and template are not in the validator's list

Both resolve correctly at execution time, but neither is an accepted prefix for this rule, so ${env.API_BASE_URL} in a connector parameter raises INVALID_EXPRESSION. Because validation is non-blocking the element still saves and still works — the finding is a false positive you can ignore.

Invalid example:

"${ This is.asdf }"

Error:

[INVALID_EXPRESSION]
Invalid dot found in element[3] adder-endpoint parameter 'addend': "This is.asdf".
Dots are only allowed after ref, response, input, params, root, output prefixes.
output is an output transformer only

${ output.* } resolves only inside an element's output transformer, where it holds that element's own result. It is not available in connector parameters. See Transforming Connectivity Input & Output Data.


Referenced ref Must Exist​

If an expression references a connector element using ref.<name>, that ref must exist in the connector.

Invalid example:

"${ This is ref.sourc12344e.source }"

Error:

[INVALID_REF]
ref 'sourc12344e' does not exist

Valid Cross-Element Reference​

Valid example:

"${ This is response.source.source }"

Explanation:

  • source is a valid connector element reference
  • response.source is a valid response path

Dots Inside Quotes Are Allowed​

Dots inside single quotes or escaped double quotes are treated as literal text and are not parsed.

Valid example using single quotes:

"${ This is 'ref.sourc123e.source' }"

Valid example using escaped double quotes:

"${ This is \"ref.sourcasdfasdf123e.source\" }"

No validation error is raised.


Summary of Connector Validation Errors​

Error codeApplies toDescription
INVALID_CONNECTORconnectorThe connector structure is not valid
INVALID_CONNECTOR_ELEMENTconnectorA referenced element is not registered
DUPLICATE_REFconnectorA connector element ref is not unique
INVALID_REFconnectorA ${ref.…} placeholder names a ref that does not exist
INVALID_RESPONSE_REFconnectorA ${response.…} placeholder names a ref that does not exist
INVALID_EXPRESSIONconnectorA dot appears after something other than an allowed prefix
INVALID_JSONallThe definition is not valid JSON
INVALID_JSONATAallAn expression is not a valid JSONata expression
INVALID_TARGETallThe element being validated is not of the expected shape
INVALID_CONTEXTallThe validation context is incomplete
SCHEMA_NOT_FOUNDschemaThe referenced schema could not be resolved
SCHEMA_MISSING_REQUIREDschemaA required property is absent
SCHEMA_ADDITIONAL_PROPERTIESschemaA property not permitted by the schema is present
SCHEMA_TYPE_MISMATCHschemaThe value is of the wrong type
SCHEMA_PROPERTY_TYPE_MISMATCHschemaA property value is of the wrong type
SCHEMA_VALIDATION_ERRORschemaSchema validation failed for another reason
RULE_EXECUTION_ERRORallA validation rule itself failed to run

Validation Philosophy​

  • Semantic validation is applied at registration time
  • Validation is non-blocking for every artifact type: a finding is reported, and the element is stored anyway
  • Validation errors provide early feedback and highlight potential runtime issues
  • Coverage is uneven. Connectors are validated thoroughly; workflows and schemas are validated against their schema; datapoints have no semantic rules at all

Example: Connector With All Validation Errors​

⚠️ This example is provided solely to illustrate the structural layout of a connector and is not intended to be a functional implementation.

Show full invalid connector example (for validation testing):

{
"id": "autotest-c1-adder-adder-connector",
"type": "connector",
"version": "0.0.1",
"displayName": "autotest-c1-adder-adder-connector",
"tags": [
"automated-testing",
"bootstrap-testing"
],
"description": "",
"deprecated": false,
"name": "adder to adder Connector",
"connector": {
"elements": [
{
"ref": "source",
"element": "adder-endpoint"
},
{
"ref": "duplicateRef",
"element": "adder-endpoint"
},
{
"ref": "duplicateRef",
"element": "adder-endpoint"
},
{
"ref": "invalidExpression",
"element": "adder-endpoint",
"parameters": {
"augend": "2",
"addend": "${ This is.asdf }"
}
},
{
"ref": "validInputRefCheck",
"element": "adder-endpoint",
"parameters": {
"augend": "2",
"addend": "${ This input.asdf root.as params.test }"
}
},
{
"ref": "correctCall",
"element": "adder-endpoint",
"parameters": {
"augend": "2",
"addend": "${ This is response.source.source }"
}
},
{
"ref": "validRefInsideSingleQuotes",
"element": "adder-endpoint",
"parameters": {
"augend": "2",
"addend": "${ This is 'ref.sourc123e.source' }"
}
},
{
"ref": "validRefInsideEscapedQuotes",
"element": "adder-endpoint",
"parameters": {
"augend": "2",
"addend": "${ This is \"ref.sourcasdfasdf123e.source\" }"
}
},
{
"ref": "invalidElement",
"element": "adder-endpoint-bla",
"parameters": {
"augend": "2",
"addend": "${ This is ref.sourc12344e.source }"
}
},
{
"element": "adder-endpoint",
"parameters": {
"augend": "2",
"addend": "${ This is ref.source.source }"
}
}
]
},
"owner": ""
}