> ## Documentation Index
> Fetch the complete documentation index at: https://docs.generalvalidation.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Resolve a canonical field comparison

> Requires the GV.APIReader application role, or a higher role (Owner > Contributor > Reader).

API · Dataset Pairs

POST `/api/v1/comparison-resolutions`

Requires the GV.APIReader application role, or a higher role (Owner > Contributor > Reader).

Operation ID · resolve\_comparison

## Request example

```bash theme={null}
curl --request POST \
  --url 'https://api.generalvalidation.com/api/v1/comparison-resolutions' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <access-token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "context": {
    "kind": "datasets",
    "sourceDatasetUuid": "11111111-2222-4333-8444-555555555555",
    "targetDatasetUuid": "aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee"
  },
  "selection": {
    "choiceId": "asPeerNumeric",
    "format": ""
  },
  "sourceField": "order_id",
  "surface": "joinKey",
  "targetField": "order_id_transformed"
}'
```

## Authentication and access

* **Required role:** GV.APIReader
* **Data classification:** metadata
* **Side effects:** none

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

## Request body

Required

### application/json

**Schema V1ComparisonResolutionRequest**

`object`

Properties

`context`— Required

`V1DatasetPairComparisonContext | V1DatasetsComparisonContext`

One of

Selected by `kind`.

**Option 1: V1DatasetPairComparisonContext**

**Schema V1DatasetPairComparisonContext**

`object`

Properties

`datasetPairUuid`— Required

`string (uuid)`

`kind`— Required

`string`

* **Constant:** `"datasetPair"`

Additional properties are not allowed.

**Option 2: V1DatasetsComparisonContext**

**Schema V1DatasetsComparisonContext**

`object`

Properties

`kind`— Required

`string`

* **Constant:** `"datasets"`

`sourceDatasetUuid`— Required

`string (uuid)`

`targetDatasetUuid`— Required

`string (uuid)`

Additional properties are not allowed.

`functionCode`

`string | null`

Any of

**Option 1: string**

`string`

* **Allowed values:** `"COUNT"`,`"COUNT_DISTINCT"`,`"MIN"`,`"MAX"`,`"AVG"`,`"SUM"`,`"VALUE"`,`"OUTER_VALUE"`,`"SET_A_IN_B"`,`"SET_B_IN_A"`,`"SET_A_EQUALS_B"`

**Option 2: null**

`null`

`selection`

`V1ComparisonSelection | null`

Any of

**Option 1: V1ComparisonSelection**

**Schema V1ComparisonSelection**

`object`

Properties

`choiceId`— Required

`string`

* **Allowed values:** `"asPeerNumeric"`,`"asText"`,`"asPeerDateTime"`

`format`

`string`

* **Default:** `""`

maximum length: 64

Additional properties are not allowed.

**Option 2: null**

`null`

`sourceField`— Required

`string`

minimum length: 1 · maximum length: 1024

`sourceObservationScope`

`V1RootObservationScope | V1CollectionObservationScope`

One of

Selected by `kind`.

**Option 1: V1RootObservationScope**

**Schema V1RootObservationScope**

`object`

Properties

`kind`

`string`

* **Constant:** `"root"`
* **Default:** `"root"`

Additional properties are not allowed.

**Option 2: V1CollectionObservationScope**

**Schema V1CollectionObservationScope**

`object`

Properties

`collectionPath`— Required

`string`

minimum length: 1 · maximum length: 1024

`kind`— Required

`string`

* **Constant:** `"collection"`

Additional properties are not allowed.

`storedBinding`

`V1ComparisonBinding | null`

Any of

**Option 1: V1ComparisonBinding**

**Schema V1ComparisonBinding**

`object`

Properties

`source`— Required

**Schema V1ComparisonBindingSide**

`object`

Properties

`format`

`string`

* **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 V1ComparisonBindingSide**

`object`

Properties

`format`

`string`

* **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.

**Option 2: null**

`null`

`surface`— Required

`string`

* **Allowed values:** `"valueField"`,`"joinKey"`

`targetField`— Required

`string`

minimum length: 1 · maximum length: 1024

`targetObservationScope`

`V1RootObservationScope | V1CollectionObservationScope`

One of

Selected by `kind`.

**Option 1: V1RootObservationScope**

**Schema V1RootObservationScope**

`object`

Properties

`kind`

`string`

* **Constant:** `"root"`
* **Default:** `"root"`

Additional properties are not allowed.

**Option 2: V1CollectionObservationScope**

**Schema V1CollectionObservationScope**

`object`

Properties

`collectionPath`— Required

`string`

minimum length: 1 · maximum length: 1024

`kind`— Required

`string`

* **Constant:** `"collection"`

Additional properties are not allowed.

Additional properties are not allowed.

Examples

Select numeric meaning for a join key · joinKeySelection

```
{
  "context": {
    "kind": "datasets",
    "sourceDatasetUuid": "11111111-2222-4333-8444-555555555555",
    "targetDatasetUuid": "aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee"
  },
  "selection": {
    "choiceId": "asPeerNumeric",
    "format": ""
  },
  "sourceField": "order_id",
  "surface": "joinKey",
  "targetField": "order_id_transformed"
}
```

Resolve a VALUE field comparison · valueField

```
{
  "context": {
    "datasetPairUuid": "88888888-8888-4888-8888-888888888888",
    "kind": "datasetPair"
  },
  "functionCode": "VALUE",
  "sourceField": "order_id",
  "surface": "valueField",
  "targetField": "order_id_transformed"
}
```

## 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](/errors).

### 200

Canonical comparison resolution.

### 401

A valid Microsoft Entra bearer token is required.

### 403

The authenticated principal does not have the required role.

### 404

The resource does not exist in this tenant.

### 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. `integer`minimum: 1

### 503

A required dependency is temporarily unavailable.

#### Headers

* **Retry-After:** Seconds to wait before retrying. `integer`minimum: 1