--- title: "Update rule" method: PATCH path: "/data-quality/v1/rules/{ruleUrn}" tags: ["Data Quality Rules"] --- # Update rule `PATCH /data-quality/v1/rules/{ruleUrn}` ## Request - Base URL: `https://your-environment.ataccama.one/api` - URL: `https://your-environment.ataccama.one/api/data-quality/v1/rules/{ruleUrn}` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) Update a rule using JSON Merge Patch ([RFC 7396](https://www.rfc-editor.org/rfc/rfc7396.html)). 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_` 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. 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 only the `urn` of each sub-entity: it must match the ID under which the sub-entity is stored, as it does before you edit the body. A mismatch is rejected with `400 Bad Request`. This happens, for example, when you move a sub-entity under a different key and leave the sub-entity's `urn` unchanged. Updates are applied to the current draft. Patching a published rule opens a new draft (`draftType: CHANGE`) on top of the latest published version. ## Path parameters - `ruleUrn` string, uri, required: A URN identifying the data quality rule resource in the Data Quality API. Format: urn:ata:{tenant}:data-quality:rule:{uuid} Example: urn:ata:acme-corp:data-quality:rule:123e4567-e89b-12d3-a456-426614174000. ## Request body - RulePatchRequest: JSON Merge Patch (RFC 7396) body for updating a Rule. **Principles applied at every level of the document:** a property you **omit** is left unchanged, a property set to **`null`** is removed, and a property with a value is set. Objects are patched recursively. Sub-entity collections are **maps keyed by the sub-entity's id (UUID)**. Recursive patching of individual sub-entities: - **update** — set the item's value to an object containing only the fields you want to change; its identity and every reference to it are preserved; - **delete** — set the item's value to `null`; - **create** — use a temporary key matching `new_`; the created item comes back in the response under its server-assigned id as a new key, carrying your temporary key as `correlationId`; - **leave alone** — simply don't mention the key. Omitting the whole map leaves the collection untouched; setting the map to `null` deletes every item in it. Nothing is ever deleted by omission, and a partial object never loses the fields it omits. Patching a published rule opens a new draft (`draftType=CHANGE`) version on top of the latest published version. - `name` string: Human-readable name of the rule. Omit to leave unchanged. Cannot be null; name is required and may only be replaced with another non-empty value. - `description` string, nullable: Optional description of the rule. - `defaultDqThreshold` DqThresholdPatch: Fields shared by a DQ threshold read and create body and its patch body. - `severity` string: @ExtensibleEnum Severity assigned to findings triggered by the threshold. - `value` integer: Threshold value as a percentage (0-100). If DQ evaluation results in fewer valid records than this percentage, an alert finding is triggered. - `urn` string, uri: A URN identifying the DQ threshold (used for triggering alert findings during processing) resource in the Data Quality API. Format: urn:ata:{tenant}:data-quality:dq-threshold:{uuid} Example: urn:ata:acme-corp:data-quality:dq-threshold:123e4567-e89b-12d3-a456-426614174000. - `stewardship` object, nullable: Stewardship assignment of the rule. - `groupUrn` string, uri: A URN identifying a group resource in the IAM API. To find a group's URN, use the Groups endpoints of the IAM API. Format: urn:ata:{tenant}:iam:group:{uuid} Example: urn:ata:acme-corp:iam:group:123e4567-e89b-12d3-a456-426614174000. - `inputGroups` object, nullable: Input groups keyed by their id (UUID). Omit to leave the collection unchanged; `null` deletes every group. Within the map, a `new_` key creates, a `null` value deletes that group, and an object value is merged into the existing one. Address existing groups and their inputs by their UUID key. A `new_` key always creates a new sub-entity under a new URN: recreating an existing input attribute this way breaks the DQ monitor mappings that reference the old one. - `implementation` RuleImplementationPatchRequest: Patch body for a rule's implementation. Send only the fields you want to change. Omitted fields are left unchanged, a nullable field set to `null` is cleared. - `ruleType` string: @ExtensibleEnum The kind of rule evaluation. `AGGREGATION` aggregates results across records; `CROSS_TABLE` evaluates across multiple tables; `SINGLE_TABLE` is the default per-record evaluation in single table. - `dqDimensionUrn` string, uri: A URN identifying the DQ dimension resource in the Data Quality API. Format: urn:ata:{tenant}:data-quality:dq-dimension:{uuid} Example: urn:ata:acme-corp:data-quality:dq-dimension:123e4567-e89b-12d3-a456-426614174000. - `fallback` RuleFallback: Fallback result applied when no condition of a rule matches. - `resultUrn` string, uri: A URN identifying the DQ dimension result resource in the Data Quality API. Format: urn:ata:{tenant}:data-quality:dq-dimension-result:{uuid} Example: urn:ata:acme-corp:data-quality:dq-dimension-result:123e4567-e89b-12d3-a456-426614174000. - `score` integer: Score assigned when the fallback applies. - `explanation` string: Explanation attached to the result when the fallback applies. - `conditions` object, nullable: Conditions keyed by their id (UUID). Omit to leave them unchanged; `null` deletes all of them. Within the map, a `new_` key creates, a `null` value deletes that condition, and an object value is merged into the existing one. - `groupByInputs` object, nullable: Group-by keys for aggregation rules, keyed by their id (UUID). Omit to leave them unchanged; `null` deletes all of them. Within the map, a `new_` key creates and a `null` value deletes that entry. An entry's target reference (`attribute` xor `variable`) is its entire content, so there is nothing to merge into an existing one. To point a group-by somewhere else, delete the entry (`null`) and create a new one with a `new_` key in the same request. - `parameters` object, nullable: Parameters keyed by their id (UUID). Omit to leave the collection unchanged; `null` deletes every parameter. Within the map, a `new_` key creates, a `null` value deletes that parameter, and an object value is merged into the existing one. - `variables` object, nullable: Variables keyed by their id (UUID). Omit to leave the collection unchanged; `null` deletes every variable. Within the map, a `new_` key creates, a `null` value deletes that variable, and an object value is merged into the existing one. ## Response `200` The updated DQ rule draft (`draftType=CHANGE`) version. In the example, one input attribute was merged (only its description changed), one was deleted and is therefore absent, and one was created under a server-assigned id with its temporary `new_` key returned as `correlationId`. - RuleResponse: Read/create body of a Rule (shared scalar fields plus the sub-entity trees). - `draftType` string, required: @ExtensibleEnum The type of the DRAFT version (NONE indicates a PUBLISHED version). It specifies what will happen to the entity if the DRAFT is published. Possible values: - `NEW` — draft proposal to create a new object. - `CHANGE` — draft proposal to change an existing object. - `DELETE` — draft proposal to delete an existing object. - `RESURRECT` — draft proposal to resurrect an already deleted object. - `NONE` — placeholder for a non-existent draft; represents a published version. The value describes the version that was returned, not the entity as a whole: a PUBLISHED version always reports NONE, even when an unpublished draft is waiting. Fetch it with `?version=DRAFT` to see the pending change. An entity that exists only as a draft is not listed and answers a default (published) read with 404. - `name` string: Human-readable name of the rule. Not unique: multiple rules can share a name. Identify a rule by its URN, never by its name. None of the rule fields is required to create a draft; `name` is required to publish it. - `description` string, nullable: Optional description of the rule. - `defaultDqThreshold` DqThresholdResponse: Fields shared by a DQ threshold read and create body and its patch body. - `severity` string: @ExtensibleEnum Severity assigned to findings triggered by the threshold. - `value` integer: Threshold value as a percentage (0-100). If DQ evaluation results in fewer valid records than this percentage, an alert finding is triggered. - `urn` string, uri, required: A URN identifying the DQ threshold (used for triggering alert findings during processing) resource in the Data Quality API. Format: urn:ata:{tenant}:data-quality:dq-threshold:{uuid} Example: urn:ata:acme-corp:data-quality:dq-threshold:123e4567-e89b-12d3-a456-426614174000. - `correlationId` string: Echo of the temporary key the client used to create this object — the `new_` key sent in the create or patch request. Matches `SubEntityKey`'s temporary-key form exactly: whatever key the client chose comes back verbatim. Returned **only** in the response to the request that created the object, so the client can resolve its temporary key to the server-assigned id, which is the object's key in the response map. Never sent by the client and never present when reading an existing entity. This is a uniform mechanism across the API: every keyed sub-entity collection, on every entity, uses the same temporary-key convention. - `stewardship` object, nullable: Stewardship assignment of the rule: an object with the `groupUrn` of the assigned group. - `groupUrn` string, uri: A URN identifying a group resource in the IAM API. To find a group's URN, use the Groups endpoints of the IAM API. Format: urn:ata:{tenant}:iam:group:{uuid} Example: urn:ata:acme-corp:iam:group:123e4567-e89b-12d3-a456-426614174000. - `inputGroups` object, nullable: Groups of input attributes the rule consumes, keyed by their id (UUID). Each input attribute has a name and data type (for example, `STRING`, `INTEGER`, or `DATE`). For cross-table rules, a child input group is marked `joined: true`. - `implementation` RuleImplementationResponse: Fields shared by a rule implementation read and create body and its patch body. - `ruleType` string: @ExtensibleEnum The type of DQ evaluation: `SINGLE_TABLE` (per-record evaluation), `AGGREGATION` (aggregates results across records), or `CROSS_TABLE` (evaluates across multiple tables). The default is `SINGLE_TABLE`. - `dqDimensionUrn` string, uri: A URN identifying the DQ dimension resource in the Data Quality API. Format: urn:ata:{tenant}:data-quality:dq-dimension:{uuid} Example: urn:ata:acme-corp:data-quality:dq-dimension:123e4567-e89b-12d3-a456-426614174000. - `fallback` RuleFallback: Fallback result applied when no condition of a rule matches. - `resultUrn` string, uri: A URN identifying the DQ dimension result resource in the Data Quality API. Format: urn:ata:{tenant}:data-quality:dq-dimension-result:{uuid} Example: urn:ata:acme-corp:data-quality:dq-dimension-result:123e4567-e89b-12d3-a456-426614174000. - `score` integer: Score assigned when the fallback applies. - `explanation` string: Explanation attached to the result when the fallback applies. - `conditions` object: The ordered conditions, keyed by their id (UUID) and evaluated in order by the `order` property of each condition. Each condition has 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` object: For `AGGREGATION` rules, defines how records are grouped before the conditions are evaluated, keyed by their id (UUID). Each entry references an input attribute or a variable of the same rule. - `parameters` object, nullable: Parameters that configure the rule, keyed by their id (UUID). - `variables` object, nullable: Variables derived from inputs and reused within the rule logic, keyed by their id (UUID). A variable is computed either from an expression or by applying transformations to an input attribute. - `urn` string, uri, required: A URN identifying the data quality rule resource in the Data Quality API. Format: urn:ata:{tenant}:data-quality:rule:{uuid} Example: urn:ata:acme-corp:data-quality:rule:123e4567-e89b-12d3-a456-426614174000. ## Other responses - `400`: Bad request. The request parameters or body are invalid. - `403`: Forbidden. You do not have permission to access the requested resource. - `404`: Not found. The requested resource does not exist. --- [API](https://skmtc.dev/ataccama/apis/ataccama-one-agentic-data-trust-platform-public-api.md) - [All operations](https://skmtc.dev/ataccama/apis/ataccama-one-agentic-data-trust-platform-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/ataccama/apis/ataccama-one-agentic-data-trust-platform-public-api/revisions/46f16e0487f8?raw)