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
| Artifact | Custom validation applied |
|---|---|
| Connector | Structure, reference uniqueness, reference existence, expression roots, element existence |
| Workflow | Workflow schema validation |
| Schema | Base schema validation, additional-properties validation |
| Datapoint | None — no datapoint-specific rules are implemented |
Every artifact additionally goes through generic JSON and JSONata parsing, and through schema validation where a schema applies.
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.
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:
| Root | Description |
|---|---|
ref | Documented output of another connector element |
response | Full HTTP response of another connector element |
input | The current execution payload |
root | The payload the connector was invoked with |
params | The parameters of the current connector element |
output | Accepted by the validator, but only resolvable in an output transformer |
env and template are not in the validator's listBoth 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:
sourceis a valid connector element referenceresponse.sourceis 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 code | Applies to | Description |
|---|---|---|
INVALID_CONNECTOR | connector | The connector structure is not valid |
INVALID_CONNECTOR_ELEMENT | connector | A referenced element is not registered |
DUPLICATE_REF | connector | A connector element ref is not unique |
INVALID_REF | connector | A ${ref.…} placeholder names a ref that does not exist |
INVALID_RESPONSE_REF | connector | A ${response.…} placeholder names a ref that does not exist |
INVALID_EXPRESSION | connector | A dot appears after something other than an allowed prefix |
INVALID_JSON | all | The definition is not valid JSON |
INVALID_JSONATA | all | An expression is not a valid JSONata expression |
INVALID_TARGET | all | The element being validated is not of the expected shape |
INVALID_CONTEXT | all | The validation context is incomplete |
SCHEMA_NOT_FOUND | schema | The referenced schema could not be resolved |
SCHEMA_MISSING_REQUIRED | schema | A required property is absent |
SCHEMA_ADDITIONAL_PROPERTIES | schema | A property not permitted by the schema is present |
SCHEMA_TYPE_MISMATCH | schema | The value is of the wrong type |
SCHEMA_PROPERTY_TYPE_MISMATCH | schema | A property value is of the wrong type |
SCHEMA_VALIDATION_ERROR | schema | Schema validation failed for another reason |
RULE_EXECUTION_ERROR | all | A 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": ""
}