DataQualityRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/gtm/main/json-schema/gtm-data-quality-request-schema.json",
  "title": "DataQualityRequest",
  "description": "Data Quality request body. `data` is a SINGLE resource whose `type` selects the domain (document-level discriminator); the batch of values is the `items[]` array inside its attributes. The whole request targets one domain, so homogeneity is structural — `items` is typed to the selected domain and cannot mix domains — and routing is unambiguous. Batch-level levers (`config`, `enrichments`) likewise live in the resource's attributes and apply to every item.",
  "x-generated": "2026-10-20",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/gtm-data-quality-api-v1-api-openapi.yml#/components/schemas/DataQualityRequest",
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "allOf": [
        {
          "$ref": "#/$defs/DataQualityRequestResource"
        }
      ],
      "description": "The primary data of the document"
    }
  },
  "$defs": {
    "AddressComponents": {
      "type": "object",
      "properties": {
        "streetNumber": {
          "type": "string",
          "description": "Street number (e.g., `123`)."
        },
        "street": {
          "type": "string",
          "description": "Street name (e.g., `Main St`)."
        },
        "unit": {
          "type": "string",
          "description": "Unit / suite / apartment designator (e.g., `Ste 200`)."
        },
        "poBox": {
          "type": "string",
          "description": "PO Box identifier, if present."
        },
        "city": {
          "type": "string",
          "description": "City name."
        },
        "county": {
          "type": "string",
          "description": "County or district."
        },
        "state": {
          "type": "string",
          "description": "State / province / region."
        },
        "postalCode": {
          "type": "string",
          "description": "Postal / ZIP code."
        },
        "postalExtension": {
          "type": "string",
          "description": "Postal code extension (e.g., ZIP+4)."
        },
        "country": {
          "type": "string",
          "description": "Country name or ISO code."
        }
      },
      "description": "Structured address components, shared by address input (`components`) and the address output value. All fields optional to support messy/partial values on both sides (for example, separate CRM columns with no country)."
    },
    "AddressInputItem": {
      "type": "object",
      "properties": {
        "address": {
          "type": "string",
          "description": "The address to process as raw text. May be a single free-text line or a partially structured value. Supply exactly one of `address` or `components` — supplying both, or neither, does not fail the whole request and neither field takes precedence; the individual item fails (its `data[i]` result carries `error` while the rest of the batch still succeeds, HTTP 200)."
        },
        "components": {
          "allOf": [
            {
              "$ref": "#/$defs/AddressComponents"
            }
          ],
          "description": "Pre-structured address input (for example, separate CRM columns). Supply exactly one of `address` or `components`. When present, the parse step is skipped."
        }
      },
      "description": "A single address value to prepare."
    },
    "AddressNormalizationRules": {
      "type": "object",
      "properties": {
        "streetLine": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/StreetLineRule"
          },
          "description": "Rules applied to the street line(s)."
        },
        "city": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/CityRule"
          },
          "description": "Rules applied to the city."
        },
        "stateProvince": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/StateProvinceRule"
          },
          "description": "Rules applied to the state/province."
        },
        "country": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/CountryRule"
          },
          "description": "Rules applied to the country."
        }
      },
      "description": "Inline address custom-normalization rules, grouped by rule group."
    },
    "AddressPrepareAttributes": {
      "type": "object",
      "required": [
        "items"
      ],
      "properties": {
        "enrichments": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/AddressRequestEnrichment"
          },
          "maxItems": 1,
          "description": "The enrichment signals to compute, applied to every item in the batch. Mutually exclusive with `config`."
        },
        "config": {
          "type": "object",
          "properties": {
            "normalizationRules": {
              "type": "object",
              "properties": {
                "rules": {
                  "allOf": [
                    {
                      "$ref": "#/$defs/AddressNormalizationRules"
                    }
                  ],
                  "description": "Inline custom-normalization rules, grouped by rule group. Mutually exclusive with `configId`."
                },
                "configId": {
                  "type": "string",
                  "description": "Identifier of a saved custom-normalization config to apply, resolved per-tenant from the authenticated request. Mutually exclusive with inline `rules`."
                }
              },
              "description": "Custom-normalization configuration (inline `rules` or saved `configId`)."
            }
          },
          "description": "Custom-normalization configuration applied to every item in the batch. Mutually exclusive with `enrichments`."
        },
        "items": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/AddressInputItem"
          },
          "minItems": 1,
          "maxItems": 30,
          "description": "The address values to prepare."
        }
      },
      "description": "Address Data Quality request. Default step: parse. Supply exactly one of `enrichments` or `config`:\n\n- `enrichments` — the enrichment signals to compute.\n- `config.normalizationRules` — custom normalization.\n\nSupplying both, or neither, is rejected."
    },
    "AddressRequestEnrichment": {
      "type": "string",
      "enum": [
        "VERIFY"
      ],
      "description": "The enrichment signals selectable on an address request."
    },
    "AddressRequestResource": {
      "type": "object",
      "required": [
        "type",
        "attributes"
      ],
      "properties": {
        "type": {
          "type": "string",
          "description": "The type of the resource",
          "default": "AddressPrepareRequest",
          "pattern": "AddressPrepareRequest"
        },
        "attributes": {
          "allOf": [
            {
              "$ref": "#/$defs/AddressPrepareAttributes"
            }
          ],
          "description": "The attributes defining the resource"
        }
      },
      "description": "Address request resource. `data` is a single resource of this type; the batch is in `attributes.items`."
    },
    "CityRule": {
      "type": "object",
      "required": [
        "type",
        "value"
      ],
      "properties": {
        "type": {
          "allOf": [
            {
              "$ref": "#/$defs/CityRuleType"
            }
          ],
          "description": "The city normalization rule to apply."
        },
        "value": {
          "allOf": [
            {
              "$ref": "#/$defs/CityRuleValue"
            }
          ],
          "description": "The value parameter for the rule."
        }
      },
      "description": "A single city normalization rule. Use only the documented `type`/`value` combinations."
    },
    "CityRuleType": {
      "type": "string",
      "enum": [
        "CASE",
        "PREFIXES",
        "PERIODS"
      ],
      "description": "City normalization rule names.",
      "x-enumDescriptions": {
        "CASE": "Letter casing of the city name.",
        "PREFIXES": "Prefix-token handling.",
        "PERIODS": "Period handling."
      }
    },
    "CityRuleValue": {
      "type": "string",
      "enum": [
        "NONE",
        "PROPER_CASE",
        "UPPERCASE",
        "LOWERCASE",
        "ABBREVIATE",
        "EXPAND",
        "ADD",
        "REMOVE"
      ],
      "description": "Legal values for city normalization rules. Valid combinations: `CASE` -> `PROPER_CASE|UPPERCASE|LOWERCASE`; `PREFIXES` -> `ABBREVIATE|EXPAND`; `PERIODS` -> `ADD|REMOVE`; any rule type may use `NONE`.",
      "x-enumDescriptions": {
        "NONE": "Leave unchanged.",
        "PROPER_CASE": "Proper (title) case (`CASE`).",
        "UPPERCASE": "Uppercase (`CASE`).",
        "LOWERCASE": "Lowercase (`CASE`).",
        "ABBREVIATE": "Abbreviate the prefix (`PREFIXES`).",
        "EXPAND": "Expand the prefix (`PREFIXES`).",
        "ADD": "Add periods (`PERIODS`).",
        "REMOVE": "Remove periods (`PERIODS`)."
      }
    },
    "CountryRule": {
      "type": "object",
      "required": [
        "type",
        "value"
      ],
      "properties": {
        "type": {
          "allOf": [
            {
              "$ref": "#/$defs/CountryRuleType"
            }
          ],
          "description": "The country normalization rule to apply."
        },
        "value": {
          "allOf": [
            {
              "$ref": "#/$defs/CountryRuleValue"
            }
          ],
          "description": "The value parameter for the rule."
        }
      },
      "description": "A single country normalization rule. Use only the documented `type`/`value` combinations."
    },
    "CountryRuleType": {
      "type": "string",
      "enum": [
        "COUNTRY_NAME",
        "COUNTRY_CODE"
      ],
      "description": "Country normalization rule names.",
      "x-enumDescriptions": {
        "COUNTRY_NAME": "Country-name representation.",
        "COUNTRY_CODE": "Country-code representation."
      }
    },
    "CountryRuleValue": {
      "type": "string",
      "enum": [
        "NONE",
        "COMMON_NAME",
        "SHORT_NAME",
        "LONG_NAME",
        "ES_NAME",
        "FR_NAME",
        "CH_NAME",
        "AR_NAME",
        "RU_NAME",
        "ALPHA2",
        "ALPHA3",
        "NUMERIC_CODE"
      ],
      "description": "Legal values for country normalization rules. Valid combinations: `COUNTRY_NAME` -> `COMMON_NAME|SHORT_NAME|LONG_NAME|ES_NAME|FR_NAME|CH_NAME|AR_NAME|RU_NAME|ALPHA2|ALPHA3|NUMERIC_CODE`; `COUNTRY_CODE` -> `ALPHA2|ALPHA3|NUMERIC_CODE`; any rule type may use `NONE`.",
      "x-enumDescriptions": {
        "NONE": "Leave unchanged.",
        "COMMON_NAME": "Common name (`COUNTRY_NAME`).",
        "SHORT_NAME": "Short name (`COUNTRY_NAME`).",
        "LONG_NAME": "Long name (`COUNTRY_NAME`).",
        "ES_NAME": "Spanish name (`COUNTRY_NAME`).",
        "FR_NAME": "French name (`COUNTRY_NAME`).",
        "CH_NAME": "Chinese name (`COUNTRY_NAME`).",
        "AR_NAME": "Arabic name (`COUNTRY_NAME`).",
        "RU_NAME": "Russian name (`COUNTRY_NAME`).",
        "ALPHA2": "ISO 3166-1 alpha-2 code (`COUNTRY_NAME`, `COUNTRY_CODE`).",
        "ALPHA3": "ISO 3166-1 alpha-3 code (`COUNTRY_NAME`, `COUNTRY_CODE`).",
        "NUMERIC_CODE": "ISO 3166-1 numeric code (`COUNTRY_NAME`, `COUNTRY_CODE`)."
      }
    },
    "DataQualityRequestResource": {
      "type": "object",
      "oneOf": [
        {
          "$ref": "#/$defs/PhoneRequestResource"
        },
        {
          "$ref": "#/$defs/EmailRequestResource"
        },
        {
          "$ref": "#/$defs/AddressRequestResource"
        },
        {
          "$ref": "#/$defs/JobTitleRequestResource"
        },
        {
          "$ref": "#/$defs/PersonNameRequestResource"
        }
      ],
      "description": "Polymorphic Data Quality request resource, discriminated by `type`. The request's `data` is exactly one of these (the document-level discriminator); the batch of values is the `items[]` array inside its attributes."
    },
    "EmailComponents": {
      "type": "object",
      "properties": {
        "localPart": {
          "type": "string",
          "description": "Local part (before the @)."
        },
        "domain": {
          "type": "string",
          "description": "Domain part (after the @)."
        }
      },
      "description": "Structured email components, shared by email input (`components`) and the email output value."
    },
    "EmailInputItem": {
      "type": "object",
      "properties": {
        "email": {
          "type": "string",
          "description": "The email address to process as raw text. Supply exactly one of `email` or `components` — supplying both, or neither, does not fail the whole request and neither field takes precedence; the individual item fails (its `data[i]` result carries `error` while the rest of the batch still succeeds, HTTP 200)."
        },
        "components": {
          "allOf": [
            {
              "$ref": "#/$defs/EmailComponents"
            }
          ],
          "description": "Pre-structured email input. Supply exactly one of `email` or `components`. When present, the parse step is skipped."
        }
      },
      "description": "A single email value to prepare."
    },
    "EmailPrepareAttributes": {
      "type": "object",
      "required": [
        "items"
      ],
      "properties": {
        "items": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/EmailInputItem"
          },
          "minItems": 1,
          "maxItems": 30,
          "description": "The email values to prepare."
        }
      },
      "description": "Email Data Quality request. Default steps: parse, validate, normalize."
    },
    "EmailRequestResource": {
      "type": "object",
      "required": [
        "type",
        "attributes"
      ],
      "properties": {
        "type": {
          "type": "string",
          "description": "The type of the resource",
          "default": "EmailPrepareRequest",
          "pattern": "EmailPrepareRequest"
        },
        "attributes": {
          "allOf": [
            {
              "$ref": "#/$defs/EmailPrepareAttributes"
            }
          ],
          "description": "The attributes defining the resource"
        }
      },
      "description": "Email request resource. `data` is a single resource of this type; the batch is in `attributes.items`."
    },
    "JobTitleInputItem": {
      "type": "object",
      "required": [
        "jobTitle"
      ],
      "properties": {
        "jobTitle": {
          "type": "string",
          "description": "The job title to normalize."
        }
      },
      "description": "A single job title value to prepare."
    },
    "JobTitleNormalizationRules": {
      "type": "object",
      "properties": {
        "jobTitle": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/JobTitleRule"
          },
          "description": "Rules applied to the job title."
        }
      },
      "description": "Inline job-title custom-normalization rules, grouped by rule group."
    },
    "JobTitlePrepareAttributes": {
      "type": "object",
      "required": [
        "items"
      ],
      "properties": {
        "config": {
          "type": "object",
          "properties": {
            "normalizationRules": {
              "type": "object",
              "properties": {
                "rules": {
                  "allOf": [
                    {
                      "$ref": "#/$defs/JobTitleNormalizationRules"
                    }
                  ],
                  "description": "Inline custom-normalization rules, grouped by rule group. Mutually exclusive with `configId`."
                },
                "configId": {
                  "type": "string",
                  "description": "Identifier of a saved custom-normalization config to apply, resolved per-tenant from the authenticated request. Mutually exclusive with inline `rules`."
                }
              },
              "description": "Custom-normalization configuration (inline `rules` or saved `configId`)."
            }
          },
          "description": "Optional custom-normalization configuration applied to every item in the batch. Presence of `config.normalizationRules` triggers the custom-normalization leg of the pipeline."
        },
        "items": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/JobTitleInputItem"
          },
          "minItems": 1,
          "maxItems": 30,
          "description": "The job title values to prepare."
        }
      },
      "description": "Job Title Data Quality request. Default step: normalize. Custom normalization is available via `config`."
    },
    "JobTitleRequestResource": {
      "type": "object",
      "required": [
        "type",
        "attributes"
      ],
      "properties": {
        "type": {
          "type": "string",
          "description": "The type of the resource",
          "default": "JobTitlePrepareRequest",
          "pattern": "JobTitlePrepareRequest"
        },
        "attributes": {
          "allOf": [
            {
              "$ref": "#/$defs/JobTitlePrepareAttributes"
            }
          ],
          "description": "The attributes defining the resource"
        }
      },
      "description": "Job title request resource. `data` is a single resource of this type; the batch is in `attributes.items`."
    },
    "JobTitleRule": {
      "type": "object",
      "required": [
        "type",
        "value"
      ],
      "properties": {
        "type": {
          "allOf": [
            {
              "$ref": "#/$defs/JobTitleRuleType"
            }
          ],
          "description": "The job-title normalization rule to apply."
        },
        "value": {
          "allOf": [
            {
              "$ref": "#/$defs/JobTitleRuleValue"
            }
          ],
          "description": "The value parameter for the rule."
        }
      },
      "description": "A single job-title normalization rule. Use only the documented `type`/`value` combinations."
    },
    "JobTitleRuleType": {
      "type": "string",
      "enum": [
        "CASE",
        "PERIODS",
        "COMMAS",
        "DEPARTMENT_LITERAL",
        "DEPARTMENT_NAMES",
        "ORDER",
        "CXO",
        "VP",
        "DIRECTOR",
        "MANAGER",
        "MODIFIER_PREFIXES",
        "MODIFIER_SUFFIXES",
        "OF_USAGE",
        "AND_USAGE",
        "HYPHENS"
      ],
      "description": "Job-title normalization rule names.",
      "x-enumDescriptions": {
        "CASE": "Letter casing of the title.",
        "PERIODS": "Period handling.",
        "COMMAS": "Comma handling.",
        "DEPARTMENT_LITERAL": "Department-literal token handling.",
        "DEPARTMENT_NAMES": "Department-name token handling.",
        "ORDER": "Ordering of the department relative to the title.",
        "CXO": "CxO token handling (for example, `Chief Executive Officer`/`CEO`).",
        "VP": "Vice-president token handling.",
        "DIRECTOR": "Director token handling.",
        "MANAGER": "Manager token handling.",
        "MODIFIER_PREFIXES": "Modifier-prefix token handling.",
        "MODIFIER_SUFFIXES": "Modifier-suffix token handling.",
        "OF_USAGE": "Handling of the word `of`.",
        "AND_USAGE": "Handling of the word `and` / ampersand.",
        "HYPHENS": "Hyphen handling."
      }
    },
    "JobTitleRuleValue": {
      "type": "string",
      "enum": [
        "NONE",
        "PROPER_CASE",
        "UPPERCASE",
        "LOWERCASE",
        "ADD",
        "REMOVE",
        "ABBREVIATE",
        "EXPAND",
        "DEPARTMENT_LAST",
        "DEPARTMENT_FIRST",
        "CONVERT_TO_COMMA",
        "CONVERT_TO_HYPHEN",
        "CONVERT_TO_AND",
        "CONVERT_TO_AMPERSAND",
        "REMOVE_SPACE",
        "PAD_WITH_SPACE"
      ],
      "description": "Legal values for job-title normalization rules. Valid combinations: `CASE` -> `PROPER_CASE|UPPERCASE|LOWERCASE`; `PERIODS` -> `ADD|REMOVE`; `COMMAS|MODIFIER_SUFFIXES` -> `REMOVE`; `DEPARTMENT_LITERAL|DEPARTMENT_NAMES|CXO|VP|DIRECTOR|MANAGER|MODIFIER_PREFIXES` -> `ABBREVIATE|EXPAND`; `ORDER` -> `DEPARTMENT_LAST|DEPARTMENT_FIRST`; `OF_USAGE` -> `REMOVE|CONVERT_TO_COMMA|CONVERT_TO_HYPHEN`; `AND_USAGE` -> `CONVERT_TO_AND|CONVERT_TO_AMPERSAND`; `HYPHENS` -> `REMOVE|REMOVE_SPACE|PAD_WITH_SPACE`; any rule type may use `NONE`.",
      "x-enumDescriptions": {
        "NONE": "Leave unchanged.",
        "PROPER_CASE": "Proper (title) case (`CASE`).",
        "UPPERCASE": "Uppercase (`CASE`).",
        "LOWERCASE": "Lowercase (`CASE`).",
        "ADD": "Add (`PERIODS`).",
        "REMOVE": "Remove (`PERIODS`, `COMMAS`, `MODIFIER_SUFFIXES`, `OF_USAGE`, `HYPHENS`).",
        "ABBREVIATE": "Abbreviate the token (`DEPARTMENT_LITERAL`, `DEPARTMENT_NAMES`, `CXO`, `VP`, `DIRECTOR`, `MANAGER`, `MODIFIER_PREFIXES`).",
        "EXPAND": "Expand the token (`DEPARTMENT_LITERAL`, `DEPARTMENT_NAMES`, `CXO`, `VP`, `DIRECTOR`, `MANAGER`, `MODIFIER_PREFIXES`).",
        "DEPARTMENT_LAST": "Place the department last (`ORDER`).",
        "DEPARTMENT_FIRST": "Place the department first (`ORDER`).",
        "CONVERT_TO_COMMA": "Convert to a comma (`OF_USAGE`).",
        "CONVERT_TO_HYPHEN": "Convert to a hyphen (`OF_USAGE`).",
        "CONVERT_TO_AND": "Convert to the word `and` (`AND_USAGE`).",
        "CONVERT_TO_AMPERSAND": "Convert to an ampersand (`AND_USAGE`).",
        "REMOVE_SPACE": "Remove surrounding space (`HYPHENS`).",
        "PAD_WITH_SPACE": "Pad with surrounding space (`HYPHENS`)."
      }
    },
    "PersonNameComponents": {
      "type": "object",
      "properties": {
        "prefix": {
          "type": "string",
          "description": "Name prefix / salutation (e.g., `Dr`, `Ms`)."
        },
        "first": {
          "type": "string",
          "description": "First / given name."
        },
        "middle": {
          "type": "string",
          "description": "Middle name or initial."
        },
        "last": {
          "type": "string",
          "description": "Last / family name."
        },
        "suffix": {
          "type": "string",
          "description": "Name suffix (e.g., `Jr`, `III`, `PhD`)."
        }
      },
      "description": "Structured person-name components, shared by person-name input (`components`) and the person-name output value. All fields optional to support messy/partial values on both sides (for example, separate CRM first/last columns)."
    },
    "PersonNameInputItem": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "The full name to process as raw text. Accepts common formats. Supply exactly one of `name` or `components` — supplying both, or neither, does not fail the whole request and neither field takes precedence; the individual item fails (its `data[i]` result carries `error` while the rest of the batch still succeeds, HTTP 200)."
        },
        "components": {
          "allOf": [
            {
              "$ref": "#/$defs/PersonNameComponents"
            }
          ],
          "description": "Pre-structured name input (for example, separate CRM first/last columns). Supply exactly one of `name` or `components`. When present, the parse step is skipped."
        }
      },
      "description": "A single person-name value to prepare."
    },
    "PersonNameNormalizationRules": {
      "type": "object",
      "properties": {
        "personName": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/PersonNameRule"
          },
          "description": "Rules applied to the name."
        }
      },
      "description": "Inline person-name custom-normalization rules, grouped by rule group."
    },
    "PersonNamePrepareAttributes": {
      "type": "object",
      "required": [
        "items"
      ],
      "properties": {
        "config": {
          "type": "object",
          "properties": {
            "normalizationRules": {
              "type": "object",
              "properties": {
                "rules": {
                  "allOf": [
                    {
                      "$ref": "#/$defs/PersonNameNormalizationRules"
                    }
                  ],
                  "description": "Inline custom-normalization rules, grouped by rule group. Mutually exclusive with `configId`."
                },
                "configId": {
                  "type": "string",
                  "description": "Identifier of a saved custom-normalization config to apply, resolved per-tenant from the authenticated request. Mutually exclusive with inline `rules`."
                }
              },
              "description": "Custom-normalization configuration (inline `rules` or saved `configId`)."
            }
          },
          "description": "Optional custom-normalization configuration applied to every item in the batch. Presence of `config.normalizationRules` triggers the custom-normalization leg of the pipeline."
        },
        "items": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/PersonNameInputItem"
          },
          "minItems": 1,
          "maxItems": 30,
          "description": "The person-name values to prepare."
        }
      },
      "description": "Person Name Data Quality request. Default steps: parse, validate, normalize. Custom normalization is available via `config`."
    },
    "PersonNameRequestResource": {
      "type": "object",
      "required": [
        "type",
        "attributes"
      ],
      "properties": {
        "type": {
          "type": "string",
          "description": "The type of the resource",
          "default": "PersonNamePrepareRequest",
          "pattern": "PersonNamePrepareRequest"
        },
        "attributes": {
          "allOf": [
            {
              "$ref": "#/$defs/PersonNamePrepareAttributes"
            }
          ],
          "description": "The attributes defining the resource"
        }
      },
      "description": "Person name request resource. `data` is a single resource of this type; the batch is in `attributes.items`."
    },
    "PersonNameRule": {
      "type": "object",
      "required": [
        "type",
        "value"
      ],
      "properties": {
        "type": {
          "allOf": [
            {
              "$ref": "#/$defs/PersonNameRuleType"
            }
          ],
          "description": "The person-name normalization rule to apply."
        },
        "value": {
          "allOf": [
            {
              "$ref": "#/$defs/PersonNameRuleValue"
            }
          ],
          "description": "The value parameter for the rule."
        }
      },
      "description": "A single person-name normalization rule. Use only the documented `type`/`value` combinations."
    },
    "PersonNameRuleType": {
      "type": "string",
      "enum": [
        "CASE",
        "FIRST_NAME",
        "MIDDLE_NAME",
        "PREFIXES",
        "SUFFIXES",
        "PERIODS_INITIALS",
        "PERIODS_PREFIXES",
        "HYPHENS"
      ],
      "description": "Person-name normalization rule names.",
      "x-enumDescriptions": {
        "CASE": "Letter casing of the name.",
        "FIRST_NAME": "First-name handling.",
        "MIDDLE_NAME": "Middle-name handling.",
        "PREFIXES": "Prefix-token handling (for example, `Dr`, `Ms`).",
        "SUFFIXES": "Suffix-token handling (for example, `Jr`, `III`).",
        "PERIODS_INITIALS": "Period handling for initials.",
        "PERIODS_PREFIXES": "Period handling for prefixes.",
        "HYPHENS": "Hyphen handling."
      }
    },
    "PersonNameRuleValue": {
      "type": "string",
      "enum": [
        "NONE",
        "PROPER_CASE",
        "UPPERCASE",
        "LOWERCASE",
        "CONVERT_TO_INITIAL",
        "ADD",
        "REMOVE"
      ],
      "description": "Legal values for person-name normalization rules. Valid combinations: `CASE` -> `PROPER_CASE|UPPERCASE|LOWERCASE`; `FIRST_NAME` -> `CONVERT_TO_INITIAL`; `MIDDLE_NAME` -> `CONVERT_TO_INITIAL|REMOVE`; `PREFIXES|SUFFIXES|HYPHENS` -> `REMOVE`; `PERIODS_INITIALS|PERIODS_PREFIXES` -> `ADD|REMOVE`; any rule type may use `NONE`.",
      "x-enumDescriptions": {
        "NONE": "Leave unchanged.",
        "PROPER_CASE": "Proper (title) case (`CASE`).",
        "UPPERCASE": "Uppercase (`CASE`).",
        "LOWERCASE": "Lowercase (`CASE`).",
        "CONVERT_TO_INITIAL": "Convert to a single initial (`FIRST_NAME`, `MIDDLE_NAME`).",
        "ADD": "Add the element (`PERIODS_INITIALS`, `PERIODS_PREFIXES`).",
        "REMOVE": "Remove the element (`MIDDLE_NAME`, `PREFIXES`, `SUFFIXES`, `PERIODS_INITIALS`, `PERIODS_PREFIXES`, `HYPHENS`)."
      }
    },
    "PhoneComponents": {
      "type": "object",
      "properties": {
        "number": {
          "type": "string",
          "description": "The phone number. On input: raw digits in national or full form (non-digit characters are tolerated). On output: the full, formatted number (the exact format depends on the normalization applied) — not a bare national component."
        },
        "countryCode": {
          "type": "string",
          "description": "Country calling code or ISO 3166-1 alpha-2 country, if already known."
        },
        "extension": {
          "type": "string",
          "description": "Extension, if present."
        }
      },
      "description": "Structured phone components, shared by phone input (`components`) and the phone output value."
    },
    "PhoneEnrichment": {
      "type": "string",
      "enum": [
        "LINE_TYPE"
      ],
      "description": "Enrichment signals available for the phone domain.",
      "x-enumDescriptions": {
        "LINE_TYPE": "Classify the line type (for example, landline, mobile, VoIP). Populates `value.lineType`."
      }
    },
    "PhoneInputItem": {
      "type": "object",
      "properties": {
        "phone": {
          "type": "string",
          "description": "The phone number to process as raw text. Accepts common formats; non-digit characters are tolerated. Supply exactly one of `phone` or `components` — supplying both, or neither, does not fail the whole request and neither field takes precedence; the individual item fails (its `data[i]` result carries `error` while the rest of the batch still succeeds, HTTP 200)."
        },
        "components": {
          "allOf": [
            {
              "$ref": "#/$defs/PhoneComponents"
            }
          ],
          "description": "Pre-structured phone input. Supply exactly one of `phone` or `components`. When present, the parse step is skipped."
        }
      },
      "description": "A single phone value to prepare."
    },
    "PhoneNormalizationRules": {
      "type": "object",
      "properties": {
        "phone": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/PhoneRule"
          },
          "description": "Rules applied to the phone number."
        }
      },
      "description": "Inline phone custom-normalization rules, grouped by rule group."
    },
    "PhonePrepareAttributes": {
      "type": "object",
      "required": [
        "items"
      ],
      "properties": {
        "enrichments": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/PhoneEnrichment"
          },
          "maxItems": 1,
          "description": "Optional signals to compute on top of the phone defaults, applied to every item in the batch."
        },
        "config": {
          "type": "object",
          "properties": {
            "normalizationRules": {
              "type": "object",
              "properties": {
                "rules": {
                  "allOf": [
                    {
                      "$ref": "#/$defs/PhoneNormalizationRules"
                    }
                  ],
                  "description": "Inline custom-normalization rules, grouped by rule group. Mutually exclusive with `configId`."
                },
                "configId": {
                  "type": "string",
                  "description": "Identifier of a saved custom-normalization config to apply, resolved per-tenant from the 

# --- truncated at 32 KB (40 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/gtm/refs/heads/main/json-schema/gtm-data-quality-request-schema.json