Workflow Validator (v2)

TODO

This page has many screenshots in the original Notion source (validator error UI, MR pipeline UI, resolution walkthroughs). Screenshots pending migration from Notion — see the Notion source for reference in the meantime.

What is the validator?

A validator is a system designed to ensure the correctness of the configurations in a workflow based on predefined rules or checks. It identifies errors and warnings that might disrupt workflows and impact the functionality of the SDKs.

• Errors are breaking issues in the workflow.
• Warnings are items that will not break the workflow but are not used in the right way.

When does this validation happen?

When a new workflow is created and a merge request is raised to merge the workflow to GitLab / S3, the validator runs on the workflow in the MR. This ensures only a valid workflow is merged into S3.

What does this document cover?

This document is a comprehensive guide to understanding and resolving issues identified by the validator. It covers:

• Issue analysis — details of common validator errors and their resolutions.
• Validation checks — a complete list of checks performed by the validator.
• Schema documentation — schemas for modules and components to ensure proper validation compliance.
• Process for new checks — how new checks are added to existing workflows and configs.

Identify and understand the issues

How to identify issues

When the pipeline fails, look for the validator_V2 job. Clicking on it shows the list of errors and warnings produced by the validator.

Important: resolve schema validations first

🚨🚨🚨  IMPORTANT: RESOLVE SCHEMA VALIDATIONS FIRST! 🚨🚨🚨

🛑 Please resolve the following schema issues BEFORE addressing any other checks:
    🔴 BASIC_SCHEMA_VALIDATION
    🔴 MODULE_SCHEMA_VALIDATION
    🔴 FORM_COMPONENT_SCHEMA_VALIDATION

⚠️ DO NOT skip these schema validations!

Structure of error/warning messages

A message looks like:

--[INCORRECT_MODULE] [Module Schema error in module of type: api module] [id: module_faceMatch_selfie_vs_aadhar] [message: "properties.requestParameters[2].type" is required]

Parsed:

ERROR_CODE: INCORRECT_MODULE
DESCRIPTION: Module Schema error.
LOCATION (In terms of Module/Condition): Workflow > Module > ID "module_faceMatch_selfie_vs_aadhar"
Message: properties.requestParameters[2].type" is required

Schemas implemented on the validator

The validator enforces schemas across several layers of the workflow. Each section is collapsible in the Notion source — the full schema text is reproduced in the source document. High-level grouping:

Workflow / main property schema

Defines workflow-level configuration under properties:

General properties

• name (string, optional), builtOnBuilder (boolean, optional), builder (object, optional), builderProperties (object, optional), description (string, optional).
• sdkVersions (object, optional) with mobile / web sub-objects.

Server-side resume

• enableServerSideResume (boolean, optional).
• serverSideResume (object, optional):
  • enable, exitOnEndStates (array of strings), auth (required if present), version (required if auth exists — 2 when auth is present, else 1 or 2).
  • auth: startModuleId (required), authState (required), mainToken (required), authToken (required), triggerModuleId (required).

UI and configuration settings

• uiConfigSource (string, valid: "default", "custom").
• textConfigSource (object — keys are 2-letter language codes, values "default"/"custom").
• inputsRequired (object; valid types: "string", "boolean", "image", "number").
• enableResumeWorkflow, resumeWorkflowDuration, secure.

Web and mobile specifics

• web.redirectToMobile (valid: "optional", "yes", "no"), web.qrRedirectBaseURL (URI), web.enforceCameraCheck ("yes"/"no"), web.showPermissionsScreen, web.returnPartialSDKResponse.
• mobile.exitIfRooted.

Modules

modules is an array of objects (required). Each module has dynamic properties per module type.

Conditional variables

conditionalVariables is an object of dynamic keys. Each variable has:

• name (optional), rule (required), parent (optional), if_true (required, can be empty), if_false (required, can be empty).

Conditions

conditions is a required object. Each condition has:

• name (optional), next_node_type (object or string, optional), rule (required), if_true (required), if_false (required).
• contributingModuleIds, contributingSuperModuleIds (arrays, min 1).
• if_true_reason, if_false_reason, if_true_ignore_results_onwards, if_false_ignore_results_onwards.
• ifTrueConfigs and ifFalseConfigs each with reason and resumeFrom.

SDK response

sdkResponse (object, optional) — dynamic string keys with values string (can be empty), boolean, or integer.

End screen configurations

endScreenConfigs (object, optional).

Dashboard data

dashboardData (object, optional) — dynamic string keys mapping to string values.

Workflow schema object (root)

workflowSchema is required and contains name, description, updatedAt, createdAt, properties (required), modules (required), conditions (required), conditionalVariables, sdkResponse, dashboardData, endScreenConfigs.

Module, component, and properties schemas

Module and component-level schemas are enforced per module/component type (api module, dynamicForm, dropdown, etc.). Refer to the Notion source for the full per-component schemas.

Predefined variables

Predefined input variables: appId, appKey, transactionId, workflowId, accessToken.

List of errors and warnings

Error codes

Error Code	Description	How to fix
DUPLICATE_ID_FOUND	Duplicate IDs found in modules or conditions.	Update the node IDs to ensure uniqueness.
SUBSTRING_FOUND_IN_ID	A moduleId is a substring of another module ID.	Ensure module IDs are distinct and not substrings of each other.
INCORRECT_WORKFLOW	The workflow schema is invalid.	Fix schema issues as per the error description.
NO_END_STATE_REACHABLE	There is no logical path to reach an end state.	Review the workflow logic and ensure at least one end state is reachable.
INVALID_NEXT_STEP	End state is listed as one of the next steps.	Ensure end states are properly configured to only appear from conditions.
UNDECLARED_NODE	A referenced node does not exist in the workflow.	Add the missing node to the workflow or update the references.
INCORRECT_MODULE	A module fails schema validation.	Correct the module schema based on the error details.
INCORRECT_FORM_COMPONENT	A form component fails schema validation.	Fix the component schema as per the error text.
MODULE_SCHEMA_NOT_FOUND	A new module type is used, but its schema is not present in the validator.	Update the validator schema to include the new module type.
CHECK_EXECUTION_FAILED	The validation check itself failed to execute.	Fix other errors first; this is likely resolved automatically afterward.
FORM_COMPONENT_SCHEMA_NOT_FOUND	A form component uses a new type not supported by the validator.	Verify and update the validator schema with the correct component type.
PARENTHESES_NOT_BALANCED	There are unmatched or unbalanced parentheses in an expression.	Ensure all parentheses in the expression are correctly balanced.
INVALID_OPERAND	An invalid operand is used in an expression.	Verify and correct the operands in the expression.
MISSING_OPERAND	An operand is missing in an expression.	Ensure all required operands are present in the expression.
INVALID_OPERATOR	An invalid operator is used in an expression.	Use valid operators in the expression.
MISSING_OPERATOR	An operator is missing between operands in an expression.	Check and add missing operators in the expression.
UNDEFINED_OPERAND	An operand in the expression is undefined.	Use null instead of undefined.
MODULE_NOT_FOUND	A referenced module is missing in the workflow.	Ensure the module exists and is correctly referenced.
CONDITION_NOT_FOUND	A referenced condition is missing in the workflow.	Add or correct the missing condition reference.
CONDITIONAL_VARIABLE_NOT_FOUND	A conditional variable is not found in the workflow.	Verify the existence of the conditional variable.
INVALID_RULE_EXPRESSION	The rule expression is invalid.	Correct syntax or logic errors in the rule expression.
UNSUPPORTED_EXPRESSION_TYPE	An unsupported expression type is used.	Use an expression type supported by the system.
VARIABLE_NOT_FOUND	A referenced variable is not found.	Ensure the variable exists and is properly referenced.
COMPONENT_NOT_FOUND	A referenced component is missing in the workflow.	Verify the component exists and is correctly referenced.

Warning codes

Warning Code	Description	How to fix
MISSING_VALIDATION_FOR_COMPONENT	A validation rule is missing for a component.	Add the appropriate validation rule for the component.
REGEX_VALIDATION_NOT_FOUND	A regex validation rule is missing.	Include the missing regex validation for the relevant field.
EMPTY_FIELD_VALUE	An input field has an empty value.	Ensure all input fields are populated with valid values.
EMPTY_REQUEST_PARAMETER_OR_BODY	A request has an empty parameter or body.	Verify and populate the request parameters and body with correct values.
MISSING_NULL_CHECK_IN_RULE	A rule does not check for null values.	Add a null check to handle potential null values in the rule.
EMPTY_IF_TRUE_OR_IF_FALSE_CONDITIONAL	The if_true or if_false condition is empty.	Define the correct conditions for both if_true and if_false scenarios.
UNVISITED_NODE	A node remains logically unvisited in the workflow.	Remove or integrate the unvisited node into the workflow logic.
SUBSTRING_FOUND_IN_ID	A moduleId is a substring of another module ID.	Ensure module IDs are distinct and not substrings of each other.

Commonly faced issues

Case 1: INCORRECT_FORM_COMPONENT

What is the issue? INCORRECT_FORM_COMPONENT indicates that a form-module component is incorrect or has an incorrect schema.

Example error context:

1. component type: dropdown
2. component id: lang
3. type: dynamicForm
4. module id: module_language_form
5. message: "labels" is required

How to resolve: Refer to the component schema documentation. For the dropdown component, labels is a required key. Add labels to the component to resolve the issue.

Case 2: UNDEFINED_OPERAND

What is the issue? UNDEFINED_OPERAND indicates that undefined was used in a rule. undefined is not supported on mobile SDKs.

Example error context:

• Issue: undefined is not supported.
• Location: condVar_aadhaar

How to resolve: Use null instead of undefined. The SDK handles the undefined check even when null is used.

FAQs

Q: Whom should we reach out to in case of issues? A: Reach out to the validator owners on Slack #proj-validator-v2 if you are not able to debug and resolve the issue.

Q: How do we find the valid schema for a component or module? A: The valid schema is documented in the schema section above; refer to the full schemas in the Notion source.

Q: What should we do if we identify that a check is working incorrectly or there is a mistake in the component schema? A: Report on Slack #proj-validator-v2 and tag the validator owners.

Process for adding new features / checks to the validator

Objective

Provide a structured approach for introducing and managing new features or checks in the validator. This process ensures clarity, minimises disruptions for SA/IE teams, and avoids unexpected issues while maintaining efficient workflows.

Scope

Categorisation, introduction, and transition process for new validator checks — from inception to implementation.

Categories of validator checks

Errors (P0s) — critical issues that block workflows or cause significant problems. Must be addressed immediately.

Warnings — non-blocking alerts indicating potential issues without disrupting workflows. Subcategories:

• High — critical warnings likely to transition to errors soon.
• Medium — important but less critical warnings.
• Low — informational alerts requiring attention but no immediate action.

Process for introducing new checks for existing workflows

1. Add as a warning — all new checks are initially categorised as warnings. Checks likely to break an SDK are flagged as P0 warnings.
2. Set a time frame — P0 warnings remain as warnings for a predefined period (e.g., one sprint). This lets relevant teams assess the check's impact and adapt their processes.
3. Transition to an error — once the period elapses and teams are aligned, the warning escalates to an error, enabling smooth adoption.

Process for new workflow keys or features

When new keys or configs are added to the workflow, they are added directly as errors. Example: when new CPR configurations are introduced to the workflow, the corresponding checks are added as errors to the validator by default.