Create a Dataset Pair

API · Dataset Pairs POST /api/v1/dataset-pairs Requires the GV.APIContributor application role, or a higher role (Owner > Contributor > Reader). Operation ID · create_dataset_pair

Request example

curl --request POST \
  --url 'https://api.generalvalidation.com/api/v1/dataset-pairs' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <access-token>' \
  --header 'Idempotency-Key: <unique-idempotency-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "joinKeys": [
    {
      "source": {
        "field": "order_id"
      },
      "target": {
        "field": "order_id"
      }
    }
  ],
  "name": "Orders source to target",
  "sourceDatasetUuid": "11111111-2222-4333-8444-555555555555",
  "targetDatasetUuid": "aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee"
}'

Authentication and access

Required role: GV.APIContributor
Data classification: metadata
Side effects: configurationWrite

Use an authentication scheme declared below. Ordinary workloads use application tokens; signed-in users use delegated tokens and Organization membership. Activation and invitation acceptance require a person, and execution callbacks require their registered identity.

Microsoft Entra delegated user token
Microsoft Entra application token

Parameters

Idempotency-Key

header Required Required caller-chosen retry identity. Use 1-128 visible ASCII characters and reuse it only for an exact retry of this request. string minimum length: 1 · maximum length: 128

Request body

Required

application/json

Schema V1DatasetPairCreate object Properties joinKeys array<V1JoinKey> Ordered source/target join bindings. Every source.field and target.field must be unique within the list. maximum items: 5 · unique by: source.field, target.field Array items Schema V1JoinKey object Properties source— Required Schema V1FieldBinding object All of Constraint 1: unknown unknown Conditional constraints

{
  "if": {
    "properties": {
      "format": {
        "pattern": "\\S"
      }
    },
    "required": [
      "format"
    ]
  },
  "then": {
    "properties": {
      "transform": {
        "enum": [
          "to_date",
          "to_timestamp"
        ]
      }
    },
    "required": [
      "transform"
    ]
  }
}

Properties field— Required string minimum length: 1 · maximum length: 1024 format string Optional parser format accepted only for date/timestamp transforms.

Default: ""

maximum length: 64 transform Schema V1FieldTransform string

Allowed values: "none","to_string","to_long","to_decimal","to_double","to_boolean","to_date","to_timestamp","to_peer_numeric"
Default: "none"

Additional properties are not allowed. target— Required Schema V1FieldBinding object All of Constraint 1: unknown unknown Conditional constraints

{
  "if": {
    "properties": {
      "format": {
        "pattern": "\\S"
      }
    },
    "required": [
      "format"
    ]
  },
  "then": {
    "properties": {
      "transform": {
        "enum": [
          "to_date",
          "to_timestamp"
        ]
      }
    },
    "required": [
      "transform"
    ]
  }
}

Properties field— Required string minimum length: 1 · maximum length: 1024 format string Optional parser format accepted only for date/timestamp transforms.

Default: ""

maximum length: 64 transform Schema V1FieldTransform string

Allowed values: "none","to_string","to_long","to_decimal","to_double","to_boolean","to_date","to_timestamp","to_peer_numeric"
Default: "none"

Additional properties are not allowed. Additional properties are not allowed. name string | null Any of Option 1: string string minimum length: 1 · maximum length: 512 Option 2: null null sourceDatasetUuid— Required string (uuid) sourceFilters array<V1ScalarFilter | V1InFilter | V1NullFilter> maximum items: 32 Array items V1ScalarFilter | V1InFilter | V1NullFilter One of Selected by operator. Option 1: V1ScalarFilter Schema V1ScalarFilter object Properties field— Required string minimum length: 1 · maximum length: 1024 operator— Required string

Allowed values: "=","<>","<","<=",">",">="

value— Required string | integer | number | boolean Any of Option 1: string string maximum length: 4096 Option 2: integer integer minimum: -9223372036854776000 · maximum: 9223372036854776000 Option 3: number number Option 4: string string pattern: ^(?!^[-+.] $)[+-]?0*(?:\d{0,26}|(?=[\d.]{1,39}0*$ )\d{0,26}.\d{0,12}0$) Option 5: boolean boolean Additional properties are not allowed. Option 2: V1InFilter Schema V1InFilter object Properties field— Required string minimum length: 1 · maximum length: 1024 operator— Required string

Constant: "in"

value— Required array<string | integer | number | boolean> minimum items: 1 · maximum items: 100 Array items string | integer | number | boolean Any of Option 1: string string maximum length: 4096 Option 2: integer integer minimum: -9223372036854776000 · maximum: 9223372036854776000 Option 3: number number Option 4: string string pattern: ^(?!^[-+.] $)[+-]?0*(?:\d{0,26}|(?=[\d.]{1,39}0*$ )\d{0,26}.\d{0,12}0$) Option 5: boolean boolean Additional properties are not allowed. Option 3: V1NullFilter Schema V1NullFilter object Properties field— Required string minimum length: 1 · maximum length: 1024 operator— Required string

Allowed values: "is_null","is_not_null"

Additional properties are not allowed. targetDatasetUuid— Required string (uuid) targetFilters array<V1ScalarFilter | V1InFilter | V1NullFilter> maximum items: 32 Array items V1ScalarFilter | V1InFilter | V1NullFilter One of Selected by operator. Option 1: V1ScalarFilter Schema V1ScalarFilter object Properties field— Required string minimum length: 1 · maximum length: 1024 operator— Required string

Allowed values: "=","<>","<","<=",">",">="

Constant: "in"

Allowed values: "is_null","is_not_null"

Additional properties are not allowed. Additional properties are not allowed. Examples Pair two imported Datasets · basic

{
  "joinKeys": [
    {
      "source": {
        "field": "order_id"
      },
      "target": {
        "field": "order_id"
      }
    }
  ],
  "name": "Orders source to target",
  "sourceDatasetUuid": "11111111-2222-4333-8444-555555555555",
  "targetDatasetUuid": "aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee"
}

Responses

This guide summarizes response status codes and headers. Retrieve the deployed, authenticated OpenAPI document for the exact response body schemas and examples. The API also provides an authenticated Swagger UI; opening it in a browser does not automatically attach a bearer token. Error responses use application/problem+json. The response’s stable code and type map to the error-code reference.

201

Dataset Pair created.

Headers

ETag: string
Idempotency-Replayed: boolean
Location: string

401

A valid Microsoft Entra bearer token is required.

402

The organization entitlement does not permit this mutation.

403

The authenticated principal does not have the required role.

404

The resource does not exist in this tenant.

409

The operation conflicts with current resource or Azure state.

422

The request is syntactically valid but semantically invalid.

429

The bounded application request rate was exceeded.

Headers

Retry-After: Seconds to wait before retrying. integerminimum: 1

503

A required dependency is temporarily unavailable.

Headers

Retry-After: Seconds to wait before retrying. integerminimum: 1

Using the API

Service capabilities

Discovery

Datasets

Dataset Pairs

Validation Functions

Validation Tests

Runs

Organization

Execution Environment

Billing

Support

Request example

Authentication and access

Parameters

Idempotency-Key

Request body

application/json

Responses

201

Headers

401

402

403

404

409

422

429

Headers

503

Headers

​Request example

​Authentication and access

​Parameters

​Idempotency-Key

​Request body

​application/json

​Responses

​201

​Headers

​401

​402

​403

​404

​409

​422

​429

​Headers

​503

​Headers

Request example

Authentication and access

Parameters

Idempotency-Key

Request body

application/json

Responses

201

Headers

401

402

403

404

409

422

429

Headers

503

Headers