Manage DQ Rules via API

The REST API is currently in Early Access Preview. The API specification and endpoints might change before being marked as stable.

We recommend testing thoroughly and being prepared to adapt to potential changes in future releases.

This guide shows you how to manage DQ rules programmatically: create rules, update their logic, and publish them for use in DQ monitors.

Before using the Data Quality API, configure authentication as described in API Authentication.

When to use this API

Use the DQ rules API when you need to:

Automate rule setup: Create rules from scripts or CI/CD pipelines instead of in the web application.
Import rules from external sources: Migrate rule definitions maintained in external tools (for example, Excel or Collibra) into Ataccama ONE.
Audit rule definitions: List and inspect the rules configured in your environment.

Limitations of the DQ rules API

Rule logic built in Condition Builder cannot be read or changed through the API. The API works with advanced expressions only, so for a condition built in Condition Builder, responses never return the logic. The stringExpression of such a condition is empty, or holds a leftover value from an earlier API request.

Sending a stringExpression for such a condition does not switch it to an advanced expression. The request succeeds and the value is stored, but the rule keeps evaluating the Condition Builder logic. The expression type can be changed only in the web application.

You can still update fields other than the expression, publish drafts, and delete the rule. To move such rules between environments, see Rules built with Condition Builder.

Draft and publish lifecycle

DQ rule changes made through the API follow a draft and publish lifecycle. Each draft has a draftType that indicates what publishing it does:

NEW: Creating a rule produces a draft of a new rule. Publishing promotes it to the first published version.
CHANGE: Updating a published rule opens a draft on top of the latest published version. Publishing promotes the draft.
DELETE: The rule is marked for deletion. Publishing deletes the rule.
RESURRECT: A deleted rule is marked for restoration. Publishing restores the rule.

DELETE and RESURRECT drafts are created in the web application only; the API never creates them, but you can retrieve them (?version=DRAFT) and publish them like any other draft. To delete a rule through the API, use the delete operation instead: it deletes the rule immediately, without a draft (see Delete a rule).

After a rule is published, it has no draft: only the published version exists, and responses report draftType: NONE. Publishing again returns the currently published version.

A rule can be created and saved as incomplete while in draft, for example without a name or implementation. However, the rule must be complete before you can publish it (see Publish a rule).

Rule structure

A rule definition consists of the following fields. None are required to create a draft; see Publish a rule for what is required to publish.

Field Description

name

Human-readable name of the rule.

description

Optional description of the rule.

inputGroups

Groups of input attributes the rule consumes. Each input attribute has a name and data type (for example, STRING, INTEGER, DATE). For cross-table rules, a child input group is marked joined: true.

implementation

The rule logic:

ruleType: The type of DQ evaluation, can be SINGLE_TABLE (per-record evaluation), AGGREGATION, or CROSS_TABLE. The default is SINGLE_TABLE.
dqDimensionUrn: The DQ dimension the rule contributes to.
conditions: The ordered conditions, each with an expression and the dimension result assigned when the evaluated data matches the condition. Expressions reference the rule’s inputs, parameters, and variables by name.
groupByInputs: For AGGREGATION rules, defines how records are grouped before the conditions are evaluated.
fallback: The dimension result assigned when the evaluated data matches no condition, optionally with a score and an explanation.

parameters

Parameters that configure the rule. Each parameter has the following properties:

name: The name by which the rule logic references the parameter.
dataType: The data type of the parameter’s value, the same data types as input attributes (for example, STRING, INTEGER, or DATE).
extendedType (optional): The kind of value the parameter holds: a list of values (LIST_OF_VALUES), a list of masks (LIST_OF_MASKS), or a regular expression (REGEX). Use an extended type when the value supplied to the rule instance is a list or a pattern, which dataType alone cannot describe. NONE means that the parameter holds a single value.

The API does not validate the value of extendedType when you create or publish the rule. A rule with an unsupported value publishes without an error, and the problem surfaces only when a DQ evaluation runs and fails.

variables

Variables derived from inputs and reused within the rule logic, computed either from an expression or by applying transformations to an input attribute.

defaultDqThreshold

Default threshold applied when the rule is used in a monitor: a value (0-100) and an optional severity (for example, WARNING or CRITICAL).

stewardship

Stewardship assignment of the rule: an object with the groupUrn of the assigned group.

The following fields are read-only and appear in responses only:

urn and draftType: Assigned automatically. On a published version, draftType is NONE.

To find the URNs of DQ dimensions, dimension results, and DQ transformations, list them via the API (see List DQ dimensions and List DQ transformations).

Example: Rule that validates the email format

The following example shows a rule definition with the fields required for publishing. The keys prefixed with new_, such as new_email, name the rule’s new sub-entities (see How to identify rule sub-entities):

{
  "name": "Email Format Validation",
  "description": "Checks that the value is a syntactically valid email address.",
  "inputGroups": {
    "new_input-group": {
      "name": "Input",
      "inputs": {
        "new_email": { "name": "email", "dataType": "STRING" }
      }
    }
  },
  "implementation": {
    "ruleType": "SINGLE_TABLE",
    "dqDimensionUrn": "urn:ata:{your-tenant}:data-quality:dq-dimension:...",
    "conditions": {
      "new_condition-1": {
        "order": 0,
        "name": "Does not match the email pattern",
        "expression": {
          "stringExpression": "not matches(@\"^\\w+\\.\\w+@\\w+$\", email)"
        },
        "resultUrn": "urn:ata:{your-tenant}:data-quality:dq-dimension-result:..."
      }
    },
    "fallback": {
      "resultUrn": "urn:ata:{your-tenant}:data-quality:dq-dimension-result:..."
    }
  }
}

Example: Rule that uses a parameter and a variable

Reference parameters and variables by name in the condition expression, in the same way as the input attributes. The parameter has no value in the rule itself: each monitor that applies the rule supplies its own value in the parameterValues field of the rule instance (see Assign rules and set thresholds).

{
  "name": "Delivery Date Valid",
  "inputGroups": {
    "new_input-group": {
      "name": "Input",
      "inputs": {
        "new_date": { "name": "date", "dataType": "DATETIME" }
      }
    }
  },
  "implementation": {
    "ruleType": "SINGLE_TABLE",
    "dqDimensionUrn": "urn:ata:{your-tenant}:data-quality:dq-dimension:...",
    "conditions": {
      "new_condition-1": {
        "order": 0,
        "name": "Date is after the deadline or in the future",
        "expression": {
          "stringExpression": "(date > deadline) or (date > current_time)"
        },
        "resultUrn": "urn:ata:{your-tenant}:data-quality:dq-dimension-result:..."
      }
    },
    "fallback": {
      "resultUrn": "urn:ata:{your-tenant}:data-quality:dq-dimension-result:..."
    }
  },
  "parameters": {
    "new_deadline": {
      "name": "deadline",
      "dataType": "DATETIME"
    }
  },
  "variables": {
    "new_current-time": {
      "name": "current_time",
      "variableType": "EXPRESSION",
      "expression": "now()"
    }
  }
}

How to identify rule sub-entities

A rule definition consists of fields, listed in the preceding table, and sub-entities inside some of them: the input groups (with their inputs), conditions, group-by inputs, parameters, and variables (with their transformations). In the preceding examples, inputGroups and inputs are fields, and the objects under the new_ keys are their sub-entities.

Because a rule can contain any number of sub-entities, each of them is identified by its own ID. This way, requests can address each sub-entity separately and leave the rest of the rule unchanged.

The ID of a sub-entity is a UUID assigned when the sub-entity is created and has the following properties:

In responses, it appears as the key under which the sub-entity is stored, for example, "7b074cbc-…": { "name": "email" } for an input. To find the IDs of existing sub-entities, retrieve the rule (see Retrieve a rule).
For sub-entities that have a urn, the ID matches the UUID part of the urn.

New sub-entities have no ID yet, so you need to name each new sub-entity yourself with a temporary key, such as new_email in the rule definition example. You can choose any temporary key that follows these rules:

It starts with new_. The prefix is what marks the sub-entity as new.
It continues with letters, digits, underscores (_), and hyphens (-), up to 36 characters. This part only helps you recognize the sub-entity in the response.
It is different for each new sub-entity in the request.

Which identifier you use depends on the request:

When creating a rule, use temporary keys to address sub-entities, since every sub-entity is new (see Create a rule).
When updating a rule, use IDs to address existing sub-entities and temporary keys for new sub-entities. One request can combine both (see Update a rule).

In either case, the response returns each new sub-entity under its assigned ID, with your temporary key in the correlationId field:

Response: New sub-entities of the rule definition example (trimmed)

{
  "inputGroups": {
    "0d94ae1c-...": {
      "name": "Input",
      "correlationId": "new_input-group",
      "inputs": {
        "7b074cbc-...": {
          "name": "email",
          "dataType": "STRING",
          "correlationId": "new_email"
        }
      }
    }
  }
}

The temporary key appears only in this one response. Later retrievals return the sub-entity without correlationId.

List rules

List the DQ rules in your environment.

Request: List DQ rules sorted by name

curl -X GET "https://{your-environment}.ataccama.one/api/data-quality/v1/rules?size=20&sort=name" \
  -H "Authorization: Bearer {access_token}"

Query parameters
Parameter	Type	Required	Description
`size`	integer	No	Number of rules to return per page. Default: `20`. Max: `100`.
`sort`	string	No	Comma-separated field names for sorting (for example, `name`). Prefix with a hyphen (`-`) for descending order.
`after`	string	No	Cursor for forward pagination. Use the value from `meta.next` in the previous response.

The response contains a data array with up to size rules, and a meta object with the pagination information:

meta.next: Cursor for retrieving the next batch of rules; pass it as the after parameter in the next request. Omitted when there are no more rules to retrieve.
meta.total: Total number of rules, across all pages.

The listing is not isolated from concurrent changes. If rules are created or deleted between page requests, some rules might be missing from the results.

List DQ dimensions and transformations

Rule definitions reference DQ dimensions, dimension results, and DQ transformations by their URNs. To find the URNs, use the following read-only listings.

List DQ dimensions

List the DQ dimensions in your environment, together with their dimension results.

Request: List DQ dimensions

curl -X GET "https://{your-environment}.ataccama.one/api/data-quality/v1/dq-dimensions" \
  -H "Authorization: Bearer {access_token}"

The endpoint returns published dimensions only, with the same forward-only pagination as List rules.

In the response, each dimension carries:

urn: The dimension’s URN, referenced as dqDimensionUrn in rule implementations.
results: All dimension results of the dimension, stored inline. The urn of a result is what rule conditions and fallbacks reference as resultUrn.
defaultConditionResultUrn and defaultFallbackResultUrn: The results assigned by default to conditions and fallbacks in that dimension.

List DQ transformations

List the DQ transformations in your environment, for use in the variables of your rules.

Request: List DQ transformations

curl -X GET "https://{your-environment}.ataccama.one/api/data-quality/v1/dq-transformations" \
  -H "Authorization: Bearer {access_token}"

The endpoint returns published transformations only, with the same forward-only pagination as List rules. By default, the transformations are sorted by group, and by name within each group.

In the response, each transformation carries:

urn: The transformation’s URN, referenced as transformationUrn in the transformations of a rule variable.
name: The display name, such as To float. Names are not unique: several transformations can share a name and differ only in the input data type. Identify a transformation by its urn, never by its name.
inputDataType: The data type the transformation accepts. A transformation can only be applied to a variable whose value is of a matching type.

The value is either one data type or a family of types. The data types are STRING, INTEGER, LONG, FLOAT, BOOLEAN, DATE, and DATETIME. The families are NUMBERS_TYPES (any numeric type), DATETIME_TYPES (any date or datetime type), and ALL_TYPES (any type).
expression: The expression the transformation applies, with the %INPUT% placeholder standing for the value the transformation is applied to.

Create a rule

Create a new rule. The rule is created as a draft (draftType: NEW) and can be incomplete: finish it via updates, then publish it to make it live. See Draft and publish lifecycle.

The request body accepts the fields described in Rule structure. If you send the read-only fields urn and draftType, they are ignored. The URN is assigned automatically and draftType is set to NEW.

Store each input group, input, condition, parameter, and variable under a temporary key that you choose, such as new_email (see How to identify rule sub-entities).

Request: Create a DQ rule with one input group

curl -X POST "https://{your-environment}.ataccama.one/api/data-quality/v1/rules" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Email Format Validation",
    "description": "Checks that the value is a syntactically valid email address.",
    "inputGroups": {
      "new_input-group": {
        "name": "Input",
        "inputs": {
          "new_email": { "name": "email", "dataType": "STRING" }
        }
      }
    }
  }'

A successful request returns 201 Created with the created rule draft, including its URN. Save the URN for publishing the rule and for assigning it to monitors.

To create many rules at once as published versions, use Create rules in batch instead.

Retrieve a rule

Retrieve a rule by URN. By default, the endpoint returns the latest published version; use ?version=DRAFT to fetch the current draft.

Request: Retrieve a DQ rule

curl -X GET "https://{your-environment}.ataccama.one/api/data-quality/v1/rules/{ruleUrn}" \
  -H "Authorization: Bearer {access_token}"

Query parameters
Parameter	Type	Required	Description
`version`	string	No	Which version of the rule to retrieve: `PUBLISHED` or `DRAFT`. If the rule has no current draft, a `DRAFT` request returns `404 Not Found`. Default: `PUBLISHED`.

The response includes the URN of each rule input attribute (the urn field of each input in inputs), which you need when mapping the rule to catalog item attributes in a DQ monitor.

Update a rule

Update a rule using JSON Merge Patch. The following rules apply to both the rule fields and its sub-entities (input groups, inputs, conditions, group-by inputs, parameters, and variables with their transformations):

To change a field or a sub-entity, send only the new values. For a sub-entity, send them under the sub-entity’s ID.
To clear a field or delete a sub-entity, set it to null.

The name field is the exception: it cannot be null, only replaced with another non-empty value.
To add a sub-entity, use a new_<id> key.
To keep anything unchanged, do not mention it in the request.

A single request can combine all of these anywhere in the rule, for example, update the description, rename one input, and delete another. New sub-entities appear in the response under their new IDs, with your temporary key returned in the correlationId field (see How to identify rule sub-entities).

The request body accepts the fields described in Rule structure. If you build the update from a retrieved rule, you can send the edited body back without removing the read-only fields, such as urn and draftType. The API checks just one of them, the urn of each sub-entity. The urn must match the ID under which the sub-entity is stored. A mismatch is rejected with 400 Bad Request.

Updates are applied to the current draft. Patching a published rule opens a new draft (draftType: CHANGE) on top of the latest published version. See Draft and publish lifecycle.

Request: Update the description, rename one input, delete another, and add a new one

curl -X PATCH "https://{your-environment}.ataccama.one/api/data-quality/v1/rules/{ruleUrn}" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Checks that the value is a syntactically valid email address (RFC 5322).",
    "inputGroups": {
      "{inputGroupId}": {
        "inputs": {
          "{inputId}": { "name": "email_address" },
          "{obsoleteInputId}": null,
          "new_currency": { "name": "currency", "dataType": "STRING" }
        }
      }
    }
  }'

The response returns the updated rule draft.

Publish a rule

Publish the current draft, promoting it to the latest published version. See Draft and publish lifecycle.

The rule must meet the following requirements; otherwise, the publish request fails with a 400 error listing what is missing:

name is set.
implementation is set, contains at least one condition, and every condition has a non-empty expression.
inputGroups contains at least one group with joined: false.

Request: Publish the rule draft

curl -X POST "https://{your-environment}.ataccama.one/api/data-quality/v1/rules/{ruleUrn}/publish" \
  -H "Authorization: Bearer {access_token}"

The response returns the published rule. If the rule has no current draft, the request still succeeds and returns the currently published version.

Delete a rule

Permanently delete a rule. This is a hard delete: both the draft and published versions are removed, and no draft is created.

Deleting a rule also removes its rule instances from all DQ monitors that apply it.

Request: Delete a rule

curl -X DELETE "https://{your-environment}.ataccama.one/api/data-quality/v1/rules/{ruleUrn}" \
  -H "Authorization: Bearer {access_token}"

A successful request returns 204 No Content.

Create rules in batch

Create up to 100 rules in a single request. Each item requires name, inputGroups, and implementation. Store each sub-entity under a temporary key that you choose, such as new_email (see How to identify rule sub-entities).

Unlike Create a rule, batch-created rules skip the draft stage and are created directly as published versions. Each rule must therefore be complete and meet the publish requirements.

Each item is processed independently: a failure on one item does not cancel the rest. The response is 207 Multi-Status. It contains a meta summary (total, success, fail) and per-item results. On success, a result carries only the URN of the created rule. On failure, it carries the error instead.

By default, results are paired with the request items by position: the first result belongs to the first item you sent. You can also add your own id to each item; the response returns it in the matching result.

Request: Create two DQ rules in one request

curl -X POST "https://{your-environment}.ataccama.one/api/data-quality/v1/rules/batch/create" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      {
        "id": "row-1",
        "name": "Email Format Validation",
        "inputGroups": { ... },
        "implementation": { ... }
      },
      {
        "id": "row-2",
        "name": "Phone Format Validation",
        "inputGroups": { ... },
        "implementation": { ... }
      }
    ]
  }'

Response: Per-item result of each created rule

{
  "meta": { "total": 2, "success": 1, "fail": 1 },
  "results": [
    {
      "id": "row-1",
      "status": "OK",
      "data": { "urn": "urn:ata:{your-tenant}:data-quality:rule:..." }
    },
    {
      "id": "row-2",
      "status": "VALIDATION_ERROR",
      "error": {
        "type": "VALIDATION_ERROR",
        "title": "Validation Error",
        "detail": "The rule implementation has no conditions."
      }
    }
  ]
}

Error handling

The API returns standard HTTP status codes and problem details for errors:

Status code Description

Status code	Description
`200 OK`	Request successful.
`201 Created`	Rule created (as a draft).
`204 No Content`	Rule deleted.
`207 Multi-Status`	Batch processed; check each item’s result for its individual outcome.
`400 Bad Request`	Invalid request parameters or body, or publishing an incomplete rule. The response body includes a `type`, `title`, `detail`, and optionally an `errors` array with specific validation failures and JSON Pointer references to the problematic fields.
`401 Unauthorized`	Invalid or expired access token.
`403 Forbidden`	Insufficient permissions to access the requested resource.
`404 Not Found`	Rule does not exist, or you requested `version=DRAFT` for a rule that has no current draft.

200 OK

Request successful.

201 Created

Rule created (as a draft).

204 No Content

Rule deleted.

207 Multi-Status

Batch processed; check each item’s result for its individual outcome.

400 Bad Request

Invalid request parameters or body, or publishing an incomplete rule. The response body includes a type, title, detail, and optionally an errors array with specific validation failures and JSON Pointer references to the problematic fields.

401 Unauthorized

Invalid or expired access token.

403 Forbidden

Insufficient permissions to access the requested resource.

404 Not Found

Rule does not exist, or you requested version=DRAFT for a rule that has no current draft.

API reference

For detailed API reference, including all endpoints, parameters, request and response schemas, and examples, see Data Quality API specification.

Next steps

Set up DQ Rules and Monitors via API: Set up DQ rules and monitors end-to-end for a new data source.
Manage DQ Monitors via API: Assign rules to DQ monitors and manage monitor configuration.
Run DQ Evaluation from Pipelines: Run DQ evaluation from your pipelines.

Was this page useful?