When working with Flow JSON, encountering the NOT_KEYWORD_SCHEMA_VALIDATION_FAILED error can be frustrating. This error typically arises due to conflicting properties that cannot exist together within a JSON component. Understanding why it occurs and how to fix it can save you time and prevent issues in your workflow.

Understanding the Error

The NOT_KEYWORD_SCHEMA_VALIDATION_FAILED error is triggered when a JSON structure violates the schema’s validation rules. Specifically, it occurs when:

  • Certain properties must be mutually exclusive, meaning they cannot be used together in the same component.

  • A specific property is incorrectly placed within a component where it is not allowed.

Example Error Messages

  • Properties '(propertyName)' and [(not_required_properties)] must be present exclusively at (componentName).

  • Properties [(not_required_properties)] must be present exclusively at (componentName).

  • Property 'success' can only be specified on a terminal screen.

Common Causes and Fixes

1. Mutually Exclusive Properties

Some properties cannot coexist in the same component. For example, in a Footer component, you cannot specify both center-caption and either left-caption or right-caption simultaneously.

Incorrect JSON

{
  "screens": [
    {
      "id": "FIRST_SCREEN",
      "layout": {
        "children": [
          {
            "type": "Footer",
            "left-caption": "left",
            "center-caption": "center",
            "on-click-action": {
              "name": "complete",
              "payloadx": {}
            }
          }
        ]
      }
    }
  ]
}

Fix

Remove one of the conflicting properties (left-caption or center-caption).

{
  "screens": [
    {
      "id": "FIRST_SCREEN",
      "layout": {
        "children": [
          {
            "type": "Footer",
            "center-caption": "center",
            "on-click-action": {
              "name": "complete",
              "payloadx": {}
            }
          }
        ]
      }
    }
  ]
}

2. Misplaced Terminal Properties

The success property should only be used in a terminal screen. If it appears on a non-terminal screen, the validation will fail.

Incorrect JSON

{
  "version": "2.1",
  "screens": [
    {
      "terminal": "false",
      "success": "true"
    }
  ]
}

Fix

Ensure success is only present when terminal is set to true.

{
  "version": "2.1",
  "screens": [
    {
      "terminal": "true",
      "success": "true"
    }
  ]
}

Tips to Debug and Prevent Schema Errors

  • Review the official documentation to understand property constraints.

  • Use a JSON schema validator to catch errors early.

  • Ensure properties are placed in the correct hierarchy.

  • If using a coding environment, enable JSON linting.

  • Ensure the structure follows API requirements.

For more troubleshooting insights related to WhatsApp Business API, check out heltar.com/blogs.