Config validation

Note

custom_types.json are a JSON-only feature and cannot be configured via the SquaredUp application. They must be created and edited directly in a plugin folder.

Config validation allows a plugin to verify that a user's configuration is valid before a data source is created.

How config validation works

When a user adds your plugin as a data source, SquaredUp runs the configured validation steps and displays the result of each step in the setup UI.

Each validation step executes a data stream and evaluates whether the request succeeds. Typically, you'll choose a lightweight data stream that requires the same authentication and permissions as the rest of the plugin.

If the request succeeds, the step passes. If the request fails, the configured error message is shown to the user.

Validation steps run in sequence and can either be informational or required. If a required step fails, the user cannot complete the data source setup until the issue is resolved.

Config validation helps users identify configuration issues early, such as invalid credentials, missing permissions, or inaccessible resources, rather than encountering them when they first use the plugin.

Adding config validation

Create a configValidation.json file at the root of your plugin folder, alongside metadata.json.

Example

{
  "steps": [
    {
      "displayName": "API access",
      "dataStream": {
        "name": "monitors"
      },
      "success": "Successfully connected to API",
      "error": "Cannot access the API — check your API key and permissions",
      "required": true
    }
  ]
}

Top-level properties

Property
Type
Description
Steps
array
Contains one or more validation steps that are executed in sequence during data source setup.

Step properties

Property
Type
Description
displayName
string
Label displayed in the validation UI for this step.
dataStream.name
string
Name of the data stream to execute. Choose a stream that will fail when credentials, permissions, or configuration are incorrect. For example, a data stream which returns a non-2xx response.
success
string
Message shown when the validation step succeeds.
error
string
Message shown when the validation step fails.
required
boolean
If true, a failing step prevents the user from completing setup.

Multiple validation steps

Plugins can define multiple validation steps to test different aspects of a configuration independently.

For example, one step might verify that authentication is working, while another confirms that the user has access to a required resource or API endpoint.

Using separate validation steps can make troubleshooting easier by showing users exactly which part of the configuration has failed.

Example

{
  "steps": [
    {
      "displayName": "API access",
      "dataStream": {
        "name": "apiStatus"
      },
      "success": "Successfully connected to the API",
      "error": "Unable to connect to the API",
      "required": true
    },
    {
      "displayName": "Project access",
      "dataStream": {
        "name": "projects"
      },
      "success": "Project access verified",
      "error": "Unable to access projects with the current credentials",
      "required": true
    }
  ]
}

Tips

  • Use a lightweight data stream for validation to minimize setup time.
  • Avoid validation streams that return large datasets or perform expensive operations.
  • Write actionable error messages that tell users what to check or change, not just that something failed. For example:
    "Check your API key has the read:monitors scope"
    Rather than:
    "Invalid credentials"
  • Use multiple validation steps when different permissions or resources need to be verified independently.

Examples

Was this article helpful?

Have more questions or facing an issue?
Submit a ticket