--- title: "Create rule" method: POST path: "/data-quality/v1/rules" tags: ["Data Quality Rules"] --- # Create rule `POST /data-quality/v1/rules` ## Request - Base URL: `https://your-environment.ataccama.one/api` - URL: `https://your-environment.ataccama.one/api/data-quality/v1/rules` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) 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. 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`. A successful request returns `201 Created` with the created rule draft. Each new sub-entity is returned under its server-assigned ID, with your temporary key in `correlationId`. Save the `urn` of the rule for publishing and assigning it to monitors. To create many rules at once as published versions, use [Create rules in batch](#tag/data-quality-rules/POST/data-quality/v1/rules/batch/create) instead. ## Request body - RuleRequest: Read/create body of a Rule (shared scalar fields plus the sub-entity trees). - `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` DqThresholdRequest: 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. - `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` RuleImplementationRequest: 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. ## Response `201` The created rule as the draft (`draftType=NEW`) version. Each sub-entity is returned under its server-assigned id (the UUID part of its `urn`), with the temporary `new_` key from the request 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. --- [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)