@pisapp/core 7.0.0-dev.20260916-153034

package/migration/API_V1_TO_V2_MIGRATION.md

@@ -0,0 +1,1424 @@
+# PIS API v1 to v2 Migration
+
+## Purpose
+
+This is the living migration guide for breaking request-contract changes between PIS API v1 and v2.
+
+Update this document in the same change set as every v2 contract change. For each change, record the affected endpoint or shared request model, v1 and v2 JSON shapes, compatibility behavior, validation, implementation status, and tests.
+
+## Versioning Policy
+
+- v1 remains supported for existing consumers and its request contracts must not change.
+- v2 uses explicit API-versioned actions and separate v2 request types where the request shape changes.
+- A v2 response remains identical to v1 unless the change is explicitly documented here.
+- Unknown legacy JSON properties are ignored by the current Newtonsoft.Json configuration. This supports phased client migration, but clients should stop sending removed properties.
+
+## Change Log
+
+| Change                                                                                                               | Status                                                                                                                | First tracked |
+| -------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | ------------- |
+| Replace v2 `AppSettings.Filters.PuId` with `InclusionCriteria` for `ProducingUnit`                                   | Standard contract mapping implemented; application-profile sales-status logic remains query-composer behavior         | 2026-08-25    |
+| Remove `AppSettings.Filters.BuId` from v2                                                                            | Implemented                                                                                                           | 2026-08-11    |
+| Replace v2 `AppSettings.Filters.SuId` with `InclusionCriteria` rules for `LocSalOrg` fields                          | Contract mapping implemented; recursive v2 query compilation pending                                                  | 2026-08-25    |
+| Represent v1 `AppSettings.Filters.SalesErp` as inclusion or exclusion criteria                                       | Internal contract mapping implemented; recursive v2 query compilation pending                                         | 2026-08-25    |
+| Replace v2 `InclusionCriteria` list with a recursive `Criteria` tree                                                 | Contract and validation implemented; includes the target replacement shape for `BuId`; Solr query compilation pending | 2026-08-11    |
+| Replace the combined v2 criteria DTO with `CriteriaGroup`/`Criterion` and rename search `filterSettings` to `filter` | Implemented                                                                                                           | 2026-09-04    |
+| Allow v2 `CriteriaGroup.rules` to be omitted, `null`, or empty                                                       | Implemented with focused validator tests; non-empty trees retain recursive validation                                 | 2026-09-07    |
+| Rename the criterion value type and OpenAPI schema from `CriteriaValue` to `CriterionValue`                          | Implemented; JSON value shape unchanged                                                                               | 2026-09-04    |
+| Add `Criteria.operator: HasValue`                                                                                    | Implemented for application inclusion/exclusion criteria and search filter settings                                   | 2026-09-01    |
+| Remove `AppSettings.AppSpecific.AssociatedGroups` and `FrontEndFilter` from v2                                       | Implemented with a dedicated `AppSpecificSettings` contract                                                           | 2026-09-01    |
+| Move `AppSettings.AppSpecific.TableRowMatching` to `AppSettings.Filters.TableRowMatching` in v2                      | Implemented with v1-to-internal-v2 conversion                                                                         | 2026-09-01    |
+| Move Detail `AppSettings.AppSpecific.RelatedProducts` to `DataTypes` in v2                                           | Implemented with v1 compatibility conversion in `DetailService`                                                       | 2026-09-01    |
+| Move Search `AppSettings.AppSpecific.TreeDepth` to top-level `SearchQuery.TreeDepth`                                 | Implemented with v1 compatibility handling in `SearchService`                                                         | 2026-09-02    |
+| Rename `AppSettings.InternalUser` to `IncludeInternalData` in v2                                                     | Implemented with v1-to-internal conversion                                                                            | 2026-09-04    |
+| Remove obsolete `InteractiveGuides` data types and response properties from v2                                       | Implemented in OpenAPI and runtime JSON                                                                               | 2026-09-07    |
+| Remove the `V2` suffix from v2 OpenAPI schema names                                                                  | Implemented without collision exceptions                                                                              | 2026-09-02    |
+| Shorten v2 `Criterion` derived OpenAPI schema names                                                                  | Implemented                                                                                                           | 2026-09-04    |
+| Make optional v2 boolean request properties nullable                                                                 | Implemented with explicit runtime fallbacks; shared catalog alias setting also changes in v1                          | 2026-09-02    |
+| Replace Translation `Components` with enum-based `Domains` and response `Component` with `Domain` in v2              | Implemented                                                                                                           | 2026-09-03    |
+| Return criterion-ready values from v2 catalog and product FilterValues endpoints                                     | Implemented; focused response-contract tests pending                                                                  | 2026-09-07    |
+| Split v2 product and relationship Filters metadata from FilterValues                                                 | Implemented; relationship v1 compatibility tests retained                                                             | 2026-09-11    |
+| Split v2 catalog Filters metadata from FilterValues                                                                  | Implemented                                                                                                           | 2026-09-14    |
+| Add filter metadata settings to v2 catalog product Search                                                            | Implemented                                                                                                           | 2026-09-14    |
+| Reduce v2 Search filter responses to metadata and add optional filter limiting                                       | Implemented                                                                                                           | 2026-09-11    |
+| Require at least one v2 Search `dataTypes` value                                                                     | Implemented                                                                                                           | 2026-09-11    |
+| Add optional `IncludeRawValues` to v2 product queries                                                                | Implemented; focused response-contract tests pending                                                                  | 2026-09-09    |
+| Add v2 sitemap products endpoint                                                                                     | Implemented for `AppSettings` and flat scalar criteria                                                                | 2026-08-11    |
+| Remove properties marked `[Obsolete]` from v2 JSON responses                                                         | Implemented with version-aware System.Text.Json metadata                                                              | 2026-09-09    |
+| Load v2 product variant table groups incrementally                                                                   | Implemented; v2 Detail returns sparse groups and `Variants/Table` loads one full group                                | 2026-09-16    |
+| Remove `AppSettings.Client` from product v2 requests                                                                 | Implemented; use standard HTTP headers and connection metadata                                                        | 2026-09-16    |
+
+## Product AppSettings.Client
+
+Product v2 requests no longer expose `appSettings.client`. Client connection metadata belongs to the HTTP request rather than application settings. This change applies to requests that use the product `AppSettingsV2` contract. Catalog v2 requests currently share `CatalogAppSettings` with v1 and are not changed by this migration item.
+
+### v1
+
+V1 continues to accept client metadata in the request body for compatibility:
+
+```json
+{
+  "appSettings": {
+    "appCode": "example-app",
+    "client": {
+      "ipAddress": "192.0.2.1",
+      "userAgent": "Mozilla/5.0 ..."
+    }
+  }
+}
+```
+
+Request headers take precedence over these legacy body values.
+
+### v2
+
+Remove `client` from `appSettings`:
+
+```json
+{
+  "appSettings": {
+    "appCode": "example-app"
+  }
+}
+```
+
+Use the existing HTTP headers instead:
+
+```http
+Component-Version: 4.12.0
+User-Agent: Mozilla/5.0 ...
+X-Forwarded-For: 192.0.2.1
+```
+
+- `Component-Version` remains unchanged and identifies the PIS component version.
+- `User-Agent` supplies browser or caller information used for analytics, device and crawler detection, and client rate limiting.
+- `X-Forwarded-For` supplies the end-user IP when a backend or reverse proxy calls PIS on the user's behalf.
+- For a browser calling PIS directly, no IP header is required; PIS uses the connection `RemoteIpAddress`.
+- For a backend-to-backend request without an end user, omit `X-Forwarded-For`; the backend connection address is used.
+
+The original client address must be first when a controlled proxy chain contains multiple addresses:
+
+```http
+X-Forwarded-For: 192.0.2.1, 198.51.100.10
+```
+
+### Rate Limiting and Proxy Requirements
+
+PIS applies both IP and client rate limiting. A backend or reverse proxy that does not forward the end-user IP and `User-Agent` causes its users to share the backend's rate-limit identities and may produce `429 TooManyRequests` responses.
+
+Only a server-side caller that obtained the address from the incoming connection should set `X-Forwarded-For`. An internet-facing proxy must overwrite an untrusted incoming value with the address that connected to it. It must not blindly append to a caller-provided value, because callers can forge HTTP headers and evade IP-based limits.
+
+### Compatibility and Tests
+
+- V1 body fallback remains supported.
+- Product v2 ignores legacy `appSettings.client` for request metadata; unknown JSON properties remain tolerated during migration.
+- Existing `Component-Version`, `User-Agent`, and `X-Forwarded-For` names are retained; no new PIS-prefixed alternatives are introduced.
+- Focused middleware tests cover header extraction, IP-chain deduplication, direct connection fallback, v1 body compatibility, and product v2 body removal.
+
+## Obsolete Response Properties
+
+Properties marked with `[Obsolete]` remain serialized by v1 endpoints for backward compatibility. V2 endpoints omit those properties from JSON responses, matching their removal from the v2 OpenAPI document. This applies recursively to shared response DTOs, including `ProductAttribute.IsInternal`; its replacement is `ProductAttribute.Internal`.
+
+## Product Attribute Raw Values
+
+The v2 product Autocomplete, Detail, List, Preview, Relationship Autocomplete, Search, and Sitemap Products requests
+accept the optional top-level `includeRawValues` property:
+
+```json
+{
+  "includeRawValues": true,
+  "appSettings": {
+    "context": {
+      "localization": {
+        "language": "en"
+      }
+    }
+  }
+}
+```
+
+When `includeRawValues` is `true`, each returned product `AttributeValue` includes a criterion-ready `rawValue`.
+Clients can pass this object directly as an item in `AttributeCriterion.values`. For scalar and enumeration
+attributes, `rawValue.V` contains the source value or enumeration code. For multidimensional attributes, the object
+also preserves the applicable header in `H` and unit of measure in `U`:
+
+```json
+{
+  "text": "50 mm",
+  "rawValue": {
+    "H": "Width",
+    "V": "50",
+    "U": "mm"
+  }
+}
+```
+
+Omitting `includeRawValues`, or sending `null` or `false`, leaves `rawValue` unset. The option changes only the
+attribute-value response data; it does not affect product matching, attribute selection, or formatted display text.
+The v1 request contracts are unchanged.
+
+## Optional CriteriaGroup Rules
+
+The shared v2 `CriteriaGroup` request model accepts `rules` when it is omitted, explicitly `null`, or an empty array. This permits clients to send an inactive filter group such as `{"type":"group","condition":"And","rules":[]}`. Non-empty groups continue to validate every nested criterion recursively. This only relaxes v2 request validation; v1 request contracts are unchanged.
+
+## Optional Boolean Request Properties
+
+Optional boolean request properties in v2 use nullable JSON values. For the properties listed below, omitting the property or sending `null` leaves the option unspecified. The service layer resolves an unspecified value to `false`, preserving the previous behavior:
+
+- `SearchQuery.includeProductClassifications`, `SearchQuery.includeExtendedObjectData`
+- `ListQuery.includeProductClassifications`
+- `AutocompleteQuery.categorySearch`, `categoryKeywordSearch`, `autoCategoryNavigation`, `fetchProductImages`, `fetchCategoryImages`
+- `PrmAutocompleteQuery.fetchProductImages`
+- `AutocompleteQuery.includeRawValues`, `DetailQuery.includeRawValues`, `ListQuery.includeRawValues`, `PreviewQuery.includeRawValues`
+- `PrmAutocompleteQuery.includeRawValues`, `SearchQuery.includeRawValues`, `SitemapProductSearchQuery.includeRawValues`
+- `CatalogProductAutocompleteQuery.fetchProductImages`
+- `AppSettings.filters.tableRowMatching`
+- `AppSettings.appSpecific.genericizeAttName`, `allReplacements`
+- `CompareSearchSettings.differencesOnly`, `specialDocumentHandling`
+- `ClassificationSearchSettings.configurators`
+- `CatalogAppSettings.appSpecific.configuredItemAliasesEnabled`
+
+`CompareSearchSettings.strictMode` is also nullable, but retains its documented default of `true`. Omitting it or sending `null` enables strict mode; clients must send `false` to disable it.
+
+The OpenAPI v2 schema represents the false-fallback properties with `nullable: true` and `default: null`. It represents `strictMode` with `nullable: true` and `default: true`.
+
+The Compare and classification settings use dedicated v2 request types, so their v1 property types remain non-nullable. `CatalogAppSpecificSettings` remains shared by both API versions and is changed directly; consequently, `configuredItemAliasesEnabled` is nullable in both v1 and v2.
+
+## AppSettings.InternalUser
+
+### v1
+
+The v1 `AppSettings` contract uses `internalUser` to request internal-only data:
+
+```json
+{
+  "appSettings": {
+    "internalUser": true
+  }
+}
+```
+
+### v2
+
+Rename the property to `includeInternalData`:
+
+```json
+{
+  "appSettings": {
+    "includeInternalData": true
+  }
+}
+```
+
+The new name describes the requested response and filtering behavior instead of identifying the caller. The property remains nullable: omitting it, sending `null`, or sending `false` does not enable internal data. Application-level authorization is still required when the value is `true`.
+
+### Compatibility and Validation
+
+- The v1 request contract and `internalUser` behavior are unchanged.
+- During v1 conversion, `internalUser` is copied to `AppSettingsInternal.IncludeInternalData`.
+- V2 requests use `includeInternalData`, which is copied to the same internal execution property.
+- The legacy `internalUser` property is absent from the v2 OpenAPI schema. If sent in a v2 payload, it is treated as an unknown property and ignored by the current Newtonsoft.Json configuration.
+- Responses are unchanged.
+
+## ApplicationFilters.PuId
+
+### v1
+
+```json
+{
+  "appSettings": {
+    "filters": {
+      "puId": ["FIDRI", "SEMOT"]
+    }
+  }
+}
+```
+
+`AppSettings.Filters.PuId` is a list of Producing Unit codes. The standard v1 query composer removes empty values and filters the `ProducingUnit` attribute, combining supplied values with `OR`.
+
+### v2
+
+Replace `appSettings.filters.puId` with one `ProducingUnit` rule in `appSettings.filters.inclusionCriteria`:
+
+```json
+{
+  "appSettings": {
+    "filters": {
+      "inclusionCriteria": {
+        "condition": "And",
+        "rules": [
+          {
+            "type": "attribute",
+            "code": "ProducingUnit",
+            "values": [{ "V": "FIDRI" }, { "V": "SEMOT" }],
+            "operator": "In"
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+The values of one `ProducingUnit` rule are alternatives, so this means `ProducingUnit = FIDRI OR ProducingUnit = SEMOT`. Place the rule in the root `And` group alongside any other inclusion rules.
+
+### Application Profile Sales-Status Logic
+
+When the current application's `ApplicationProfile` enables `ExtraPuIdProductSalesStatusLogic`, clients still send only the `ProducingUnit` criterion shown above. During query compilation, PIS automatically expands every `ProducingUnit` value with an `OR` alternative for `ProductSalesStatus_PU{producingUnit}` equal to `A`, `O`, or `P`.
+
+For example, with `FIDRI`, PIS applies `ProducingUnit = FIDRI OR ProductSalesStatus_PUFIDRI = A|O|P`. Do not add `ProductSalesStatus_PU...` rules to the v2 request; the application profile controls whether the expansion is active.
+
+### Compatibility and Validation
+
+- The v1-to-internal-v2 conversion removes empty `puId` entries and adds one `ProducingUnit` rule to `inclusionCriteria` when values remain.
+- The `ExtraPuIdProductSalesStatusLogic` application-profile flag changes query composition to also match `ProductSalesStatus_PU{puId}` values `A`, `O`, and `P`. The `ProducingUnit` criteria compiler applies this profile-dependent behavior, preserving the v1 result set.
+- The standard `ProducingUnit` replacement is a flat scalar criterion supported by `POST /v2/Sitemap/Products`.
+- Other product endpoints do not execute `Criteria` yet.
+
+## ApplicationFilters.BuId
+
+### v1
+
+```json
+{
+  "appSettings": {
+    "filters": {
+      "buId": ["3127", "3119", "3129"]
+    }
+  }
+}
+```
+
+`AppSettings.Filters.BuId` is a `List<string>` and limits results by ABB Detail Group.
+
+The current v1 query composer creates one filter for the attribute field `BuId` and combines the supplied values with `OR`. For example, `["3127", "3119", "3129"]` means: product `BuId` is `3127` OR product `BuId` is `3119` OR product `BuId` is `3129`.
+
+### v2
+
+`appSettings.filters.buId` is removed from `ApplicationFilters`.
+
+The v2 replacement is `appSettings.filters.inclusionCriteria` with `code` set to `BuId`:
+
+```json
+{
+  "appSettings": {
+    "filters": {
+      "inclusionCriteria": {
+        "condition": "And",
+        "rules": [
+          {
+            "type": "attribute",
+            "code": "BuId",
+            "values": [{ "V": "3127" }, { "V": "3119" }, { "V": "3129" }],
+            "operator": "In"
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+This is a single `Criteria` group, not an array. The group contains one `BuId` rule whose values have the expected semantics `BuId = 3127 OR BuId = 3119 OR BuId = 3129`, matching v1.
+
+Do not send `H` or `U` for `BuId`. Put each ABB Detail Group code directly in `values[].V`.
+
+### Client Migration
+
+1. Stop sending `appSettings.filters.buId` to v2 endpoints.
+2. Use one `inclusionCriteria` group with `condition: "And"` and one `BuId` rule in `rules`.
+3. Copy every v1 `buId` list item to a separate `rules[0].values[].V` entry.
+4. Use the replacement in `POST /v2/Sitemap/Products`; other product endpoints do not execute `Criteria` yet.
+5. Send the remaining supported v2 filter properties unchanged until their own migration entry says otherwise.
+
+### Compatibility and Validation
+
+- v1 behavior is unchanged.
+- A v2 payload containing legacy `buId` is currently accepted and the unknown property is ignored.
+- `BuId` is not present in the v2 OpenAPI schema and is not validated by the v2 application-settings validator.
+
+## ApplicationFilters.SuId
+
+### v1
+
+```json
+{
+  "appSettings": {
+    "filters": {
+      "suId": ["SUDESTO", "SUNOCRL"]
+    }
+  }
+}
+```
+
+`AppSettings.Filters.SuId` identifies sales units. The v1 query composer discards empty values and values shorter than three characters. For each remaining value it queries the attribute field `LocSalOrg` followed by the value starting at index `2`, and compares that field with the complete `SuId` value. Multiple `SuId` filters are combined with `OR`.
+
+### v2
+
+Apply the same logic with an `Or` group in `appSettings.filters.inclusionCriteria`:
+
+```json
+{
+  "appSettings": {
+    "filters": {
+      "inclusionCriteria": {
+        "condition": "And",
+        "rules": [
+          {
+            "type": "group",
+            "condition": "Or",
+            "rules": [
+              {
+                "type": "attribute",
+                "code": "LocSalOrgDESTO",
+                "values": [{ "V": "SUDESTO" }],
+                "operator": "In"
+              },
+              {
+                "type": "attribute",
+                "code": "LocSalOrgNOCRL",
+                "values": [{ "V": "SUNOCRL" }],
+                "operator": "In"
+              }
+            ]
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+For every valid `suId`, create one rule with `code` equal to `LocSalOrg` plus `suId.substring(2)`, and place the complete `suId` in `values[0].value`. Put all generated rules in one `Or` group. Place that group in the root `And` group alongside any other inclusion rules, preserving the v1 behavior.
+
+### Compatibility and Validation
+
+- When a v1 `AppSettings` request is converted to internal v2 criteria, `SuId` is mapped to the nested `Or` group described above.
+- Values that are empty after cleanup or shorter than three characters do not produce a criterion, matching the v1 query composer.
+- `POST /v2/Sitemap/Products` currently rejects nested `rules`; therefore it cannot execute the multi-`SuId` v2 shape until recursive query compilation is implemented.
+- Other product endpoints do not execute `Criteria` yet.
+
+## ApplicationFilters.SalesErp
+
+### v1
+
+````json
+{
+  "appSettings": {
+    "filters": {
+      "salesErp": true
+    }
+  }
+### v2
+
+`ApplicationFilters.SalesErp` remains supported and has the same boolean behavior. The equivalent criteria representation used for the internal v1-to-v2 conversion is:
+
+```json
+{
+  "appSettings": {
+    "filters": {
+      "inclusionCriteria": {
+        "condition": "And",
+        "rules": [
+          {
+            "type": "attribute",
+            "code": "SalesErp",
+            "values": [{ "V": "Y" }],
+            "operator": "In"
+          }
+        ]
+      }
+    }
+  }
+}
+````
+
+For `salesErp: false`, use the same rule in `exclusionCriteria` instead:
+
+```json
+{
+  "appSettings": {
+    "filters": {
+      "exclusionCriteria": {
+        "condition": "And",
+        "rules": [
+          {
+            "type": "attribute",
+            "code": "SalesErp",
+            "values": [{ "V": "Y" }],
+            "operator": "In"
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+### Compatibility and Validation
+
+- The v1-to-internal-v2 conversion adds `SalesErp = "Y"` to `inclusionCriteria` for `true` and to `exclusionCriteria` for `false`.
+- `salesErp: null` does not add a criterion.
+- `ApplicationFilters.SalesErp` remains available for v2 clients and is passed through unchanged.
+- `POST /v2/Sitemap/Products` supports only flat scalar criteria; both examples above are flat scalar groups, although recursive query composition remains pending for other endpoints.
+
+## ApplicationFilters.InclusionCriteria
+
+### v1
+
+```json
+{
+  "appSettings": {
+    "filters": {
+      "inclusionCriteria": [
+        {
+          "code": "Color",
+          "values": ["Red", "Blue"]
+        },
+        {
+          "code": "Voltage",
+          "values": ["230"]
+        }
+      ]
+    }
+  }
+}
+```
+
+```csharp
+public List<Criteria>? InclusionCriteria { get; set; }
+```
+
+### v2
+
+```json
+{
+  "appSettings": {
+    "filters": {
+      "inclusionCriteria": {
+        "condition": "And",
+        "rules": [
+          {
+            "type": "attribute",
+            "code": "Color",
+            "values": [{ "V": "Red" }, { "V": "Blue" }],
+            "operator": "In"
+          },
+          {
+            "type": "attribute",
+            "code": "Voltage",
+            "values": [
+              { "V": "230", "U": "V" },
+              { "V": "400", "U": "V" }
+            ],
+            "operator": "In"
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+```csharp
+public CriteriaGroup? InclusionCriteria { get; set; }
+```
+
+The root is always a `CriteriaGroup` with `condition` and `rules`. Every item in `rules` is a polymorphic `Criterion`
+and requires `type: "attribute"` or `type: "group"`. An `AttributeCriterion` has `code`, optional `values`, and
+`operator`; a nested `CriteriaGroup` has its own `condition` and `rules`. The root does not require `type` because its
+contract type is already `CriteriaGroup`.
+
+Each item in `AttributeCriterion.values` uses the `CriterionValue` .NET type and OpenAPI schema. This replaces the
+previous `CriteriaValue` name so that the value is associated with one criterion. Its JSON representation remains
+unchanged and contains required `V` plus optional `H` and `U` properties.
+
+### Replacing BuId with InclusionCriteria
+
+To migrate this v1 request:
+
+```json
+{
+  "appSettings": {
+    "filters": {
+      "buId": ["3127", "3119", "3129"]
+    }
+  }
+}
+```
+
+send this v2 request shape instead:
+
+```json
+{
+  "appSettings": {
+    "filters": {
+      "inclusionCriteria": {
+        "condition": "And",
+        "rules": [
+          {
+            "type": "attribute",
+            "code": "BuId",
+            "values": [{ "V": "3127" }, { "V": "3119" }, { "V": "3129" }],
+            "operator": "In"
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+The compiler for a product endpoint must translate the nested `BuId` rule to one exact attribute filter on `BuId` and OR its values. It must not require `H` or `U`, and it must not translate the codes as display labels.
+
+The criteria model contains:
+
+| Property     | Requirement in v2                                          | Notes                                                               |
+| ------------ | ---------------------------------------------------------- | ------------------------------------------------------------------- |
+| `type`       | Required for every item in `rules`: `attribute` or `group` | Not required on the root `CriteriaGroup`.                           |
+| `condition`  | Required for a `CriteriaGroup`: `And` or `Or`              | Combines the group's nested `rules`.                                |
+| `code`       | Required for an `AttributeCriterion`, non-empty            | Attribute code or `CID`.                                            |
+| `values`     | Required and non-empty for `In`; omitted for `HasValue`    | Every `In` item requires a non-empty `V`.                           |
+| `values[].H` | Optional                                                   | Used for multidimensional values.                                   |
+| `values[].U` | Optional                                                   | Used for multidimensional values.                                   |
+| `rules`      | Required for a `CriteriaGroup`, non-empty recursive list   | Every nested item is an `AttributeCriterion` or `CriteriaGroup`.    |
+| `operator`   | Required for an `AttributeCriterion`: `In` or `HasValue`   | `In` matches one of `values`; `HasValue` matches any indexed value. |
+
+### HasValue Operator
+
+Use `HasValue` when only the presence of an indexed attribute value matters:
+
+```json
+{
+  "condition": "And",
+  "rules": [
+    {
+      "type": "attribute",
+      "code": "BimRelevance",
+      "operator": "HasValue"
+    }
+  ]
+}
+```
+
+Do not send `values` for this operator. The validator rejects a non-empty `values` collection because its contents
+would be ignored. Query composition emits a Solr field-existence filter (`field:*`); exclusion criteria negate that
+filter. For translated attributes, PIS checks the active language, English fallback, and country-specific language
+fields. The v1 request contract is unchanged and does not expose this operator. Responses and cache behavior are
+unchanged.
+
+### Client Migration
+
+1. Replace the v1 array with one root `CriteriaGroup`.
+2. Set the group's `condition` and put each attribute criterion in `rules`.
+3. Add `type: "attribute"` to attribute criteria and `type: "group"` to nested groups.
+4. Convert each v1 string value to `{ "V": "..." }` in the matching rule's `values`.
+5. For a `BuId` migration, use a `BuId` rule and preserve the v1 list as OR alternatives in that rule's `values`.
+6. Use `H`, `V`, and `U` for multidimensional filter values instead of exposing the internal index separator.
+
+### Search Filter Property Rename
+
+The v2 search contracts for product search, PRM search, product preview, and catalog product search replace
+`filterSettings` with `filter`:
+
+```csharp
+public CriteriaGroup? Filter { get; set; }
+```
+
+This is a breaking request-contract change. Clients must stop sending `search.filterSettings`; unknown legacy
+properties are ignored and therefore do not filter results. The v1 contracts retain their existing
+`List<FilterSettings>? FilterSettings` property.
+
+### Current Implementation Status
+
+- `ApplicationFilters.InclusionCriteria` and `ExclusionCriteria` use `CriteriaGroup`.
+- Recursive groups are represented by `CriteriaGroup`; leaves are represented by `AttributeCriterion` through the polymorphic `Criterion` base type.
+- Recursive structure and required values are validated by `CriteriaGroupValidator` and `AttributeCriterionValidator`.
+- Product query composition supports recursive inclusion/exclusion groups, `In`, `HasValue`, multidimensional values, and `CID` criteria.
+- Search `filter` processing preserves the existing filter-settings behavior: direct attribute rules are combined with AGM predefined filters and applied to product queries.
+- The v2 `Translations` endpoint accepts `AppSettings`, but it does not apply product filters. Its availability does not imply that v2 search filtering is available.
+
+## AppSettings.AppSpecific
+
+`AppSettings.AppSpecific` uses the dedicated `AppSpecificSettings` contract. The `associatedGroups` and
+`frontEndFilter` properties are removed from this object. In v2, apply them through attribute criteria in
+`appSettings.filters`.
+
+### AssociatedGroups
+
+#### v1
+
+`AppSettings.AppSpecific.AssociatedGroups` restricts results to products belonging to one of the specified associated
+groups:
+
+```json
+{
+  "appSettings": {
+    "appSpecific": {
+      "associatedGroups": ["0229/0x Platform63", "0229/1x Platform63"]
+    }
+  }
+}
+```
+
+#### v2
+
+Move the non-empty values to one `AssociatedGroups` rule in `appSettings.filters.inclusionCriteria`:
+
+```json
+{
+  "appSettings": {
+    "filters": {
+      "inclusionCriteria": {
+        "condition": "And",
+        "rules": [
+          {
+            "type": "attribute",
+            "code": "AssociatedGroups",
+            "values": [{ "V": "0229/0x Platform63" }, { "V": "0229/1x Platform63" }],
+            "operator": "In"
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+The values in this rule are alternatives. A product is included when its `AssociatedGroups` attribute equals
+`0229/0x Platform63` OR `0229/1x Platform63`. Place the rule in the root `And` inclusion group alongside other
+inclusion rules.
+
+#### Client Migration
+
+1. Stop sending `appSettings.appSpecific.associatedGroups` to v2 endpoints.
+2. Add one rule with `code: "AssociatedGroups"` and `operator: "In"` to `appSettings.filters.inclusionCriteria.rules`.
+3. Copy every non-empty v1 list item to a separate `values[].V` entry.
+4. Preserve existing inclusion rules in the same root `And` group.
+
+### FrontEndFilter
+
+#### v1
+
+`AppSettings.AppSpecific.FrontEndFilter` excludes products whose `FrontEndFilter` attribute matches one of the
+specified values:
+
+```json
+{
+  "appSettings": {
+    "appSpecific": {
+      "frontEndFilter": ["FlameScanner", "LsoCATBXEcatalog"]
+    }
+  }
+}
+```
+
+#### v2
+
+Move the non-empty values to one `FrontEndFilter` rule in `appSettings.filters.exclusionCriteria`:
+
+```json
+{
+  "appSettings": {
+    "filters": {
+      "exclusionCriteria": {
+        "condition": "And",
+        "rules": [
+          {
+            "type": "attribute",
+            "code": "FrontEndFilter",
+            "values": [{ "V": "FlameScanner" }, { "V": "LsoCATBXEcatalog" }],
+            "operator": "In"
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+The values in this rule are alternatives. A product is excluded when its `FrontEndFilter` attribute equals
+`FlameScanner` OR `LsoCATBXEcatalog`. Place the rule in the root `And` exclusion group alongside other exclusion
+rules.
+
+#### Client Migration
+
+1. Stop sending `appSettings.appSpecific.frontEndFilter` to v2 endpoints.
+2. Add one rule with `code: "FrontEndFilter"` and `operator: "In"` to `appSettings.filters.exclusionCriteria.rules`.
+3. Copy every non-empty v1 list item to a separate `values[].V` entry.
+4. Preserve existing exclusion rules in the same root `And` group.
+
+### Compatibility and Validation
+
+- v1 requests and behavior are unchanged. During conversion, `associatedGroups` becomes an `AssociatedGroups` rule in the root `And` group of `inclusionCriteria`, and `frontEndFilter` becomes a `FrontEndFilter` rule in the root `And` group of `exclusionCriteria`.
+- Each converted list becomes the `V` values of an `In` rule. Empty entries are discarded, matching the existing v1 query behavior.
+- `AppSettingsInternal.AppSpecific` uses `AppSpecificSettings`, so the removed fields do not exist in the canonical execution model.
+- Supported v1 and v2 app-specific settings are copied into that v2 internal contract.
+- A v2 payload containing legacy `associatedGroups` or `frontEndFilter` is currently accepted and those unknown properties are ignored.
+- The removed properties are absent from the v2 OpenAPI schema. Responses are unchanged.
+
+## Search TreeDepth
+
+### v1
+
+The Search endpoint accepts `TreeDepth` as an application-specific setting. Although the property is part of the
+shared `AppSettings.AppSpecific` contract, it is used only by `POST /v1/Products/Search`; other v1 controllers do not
+consume it:
+
+```json
+{
+  "dataTypes": ["Classifications"],
+  "appSettings": {
+    "appSpecific": {
+      "treeDepth": 2
+    }
+  }
+}
+```
+
+It controls how deeply the classification tree in the Search response is expanded. A missing value or `0` keeps the
+default behavior.
+
+### v2
+
+Move the property to the top level of `SearchQuery`:
+
+```json
+{
+  "dataTypes": ["Classifications"],
+  "treeDepth": 2,
+  "appSettings": {
+    "appCode": "example"
+  }
+}
+```
+
+`TreeDepth` is an option of `POST /v2/Products/Search`, alongside other response-shaping settings such as
+`MaxClassificationImages`. It is not part of the shared `SearchSettings` contract and does not affect product
+matching. The property is nullable and defaults to `null`. A missing value, `null`, or `0` preserves the existing
+default behavior.
+
+### Client Migration
+
+1. Stop sending `appSettings.appSpecific.treeDepth` to the v2 Search endpoint.
+2. Send the same integer as top-level `treeDepth` in `SearchQuery`.
+3. Keep `search.cid` and the remaining search criteria under `search` unchanged.
+
+### Compatibility and Validation
+
+- The v1 request contract and behavior are unchanged. `SearchService` reads the legacy value from
+  `AppSettings.AppSpecific.TreeDepth` for v1 requests.
+- The v2 Search endpoint reads only top-level `SearchQuery.TreeDepth` and treats `null` as `0`.
+- A v2 payload containing legacy `appSettings.appSpecific.treeDepth` is currently accepted and the unknown property is
+  ignored.
+- This move does not add range validation; accepted values retain the existing Search behavior.
+- The classification response shape, facet selection behavior, and cache behavior are unchanged.
+- `SearchSettings` remains unchanged because it is shared by other queries.
+- The Classifications endpoint remains unchanged and continues to use `ClassificationSearchSettings.TreeDepth`.
+- `TreeDepth` is removed from the v2 `AppSpecificSettings` OpenAPI schema and exposed as a nullable property directly
+  on `SearchQuery`.
+
+## AppSpecific.TableRowMatching
+
+### v1
+
+`TableRowMatching` is an application-specific setting:
+
+```json
+{
+  "appSettings": {
+    "appSpecific": {
+      "tableRowMatching": true
+    }
+  }
+}
+```
+
+When enabled, criteria for attributes stored in product tables are evaluated against individual rows instead of the
+entire table data set.
+
+### v2
+
+Move the property under `appSettings.filters` using the same name:
+
+```json
+{
+  "appSettings": {
+    "filters": {
+      "tableRowMatching": true
+    }
+  }
+}
+```
+
+### Client Migration
+
+1. Stop sending `appSettings.appSpecific.tableRowMatching` to v2 endpoints.
+2. Send the same boolean value as `appSettings.filters.tableRowMatching`.
+3. Keep table attribute criteria in the applicable inclusion, exclusion, or search filter settings.
+
+### Compatibility and Validation
+
+- v1 requests and behavior are unchanged. The v1-to-internal-v2 conversion copies a true value from `AppSpecific` to `ApplicationFilters`.
+- `AppSpecificSettings` no longer exposes `TableRowMatching`; `ApplicationFilters` exposes it with a default value of `false`.
+- A v2 payload containing legacy `appSpecific.tableRowMatching` is currently accepted and the unknown property is ignored.
+- The move changes only the v2 request shape. Table-row query and facet behavior are unchanged.
+
+## Detail RelatedProducts
+
+### v1
+
+The Detail endpoint accepts `RelatedProducts` as an application-specific setting:
+
+```json
+{
+  "dataTypes": ["ProductDetails"],
+  "appSettings": {
+    "appSpecific": {
+      "relatedProducts": true
+    }
+  }
+}
+```
+
+### v2
+
+Request related products directly as a Detail response section:
+
+```json
+{
+  "dataTypes": ["RelatedProducts"],
+  "appSettings": {
+    "appCode": "example"
+  }
+}
+```
+
+`ProductDetails` and `RelatedProducts` are independent response sections. Include both values in `dataTypes` when
+both sections are required.
+
+### Client Migration
+
+1. Stop sending `appSettings.appSpecific.relatedProducts` to the v2 Detail endpoint.
+2. Add `RelatedProducts` to the top-level `dataTypes` set when the related-products section is required.
+3. Add `ProductDetails` separately when the core product-detail section is also required.
+
+### Compatibility and Validation
+
+- The v1 request contract is unchanged. For `DetailQuery`, a true legacy setting is converted to an effective
+  `RelatedProducts` data type without modifying the request object.
+- `AppSpecificSettings` and the canonical internal app-specific settings no longer expose `RelatedProducts`.
+- A v2 payload containing legacy `appSpecific.relatedProducts` is currently accepted and the unknown property is
+  ignored; only `dataTypes` controls the v2 response section.
+- The response DTOs are unchanged. The service no longer returns `ProductDetails` implicitly when only related
+  products are requested, or related products when only product details are requested.
+- The v2 OpenAPI schema exposes `RelatedProducts` in `DetailDataTypeEnum` and omits it from
+  `AppSpecificSettings`.
+
+## Product Variant Table Groups
+
+V2 product details now support incremental loading of variant table groups. This reduces the initial Detail response
+while preserving the complete v1 response contract.
+
+### v1
+
+The v1 Detail endpoint continues to return `ProductVariantsTable` with every group containing both
+`variantAttributes` and `products` when `ProductVariantsTable` is requested. The v1 request and response contracts are
+unchanged.
+
+### v2 Detail
+
+When `dataTypes` contains `ProductVariantsTable`, the first available group is returned with its complete
+`variantAttributes` and `products` lists. Remaining groups contain only `attributeCode`, `attributeName`, and
+`attributeValueText`; their `variantAttributes` and `products` properties are omitted from JSON.
+
+```json
+{
+  "productVariantsTable": {
+    "items": [
+      {
+        "attributeCode": "Color",
+        "attributeName": "Color",
+        "attributeValueText": "Red",
+        "variantAttributes": [],
+        "products": []
+      },
+      {
+        "attributeCode": "Voltage",
+        "attributeName": "Voltage",
+        "attributeValueText": "230 V"
+      }
+    ]
+  }
+}
+```
+
+The first group means the first group with a non-empty value for the selected product, following the configured
+variant attribute order. The response uses a v2-specific DTO with nullable sparse properties; v1 continues to use its
+required properties.
+
+### Load One Group
+
+Use the v2 endpoint below to load a complete group after receiving the sparse Detail response:
+
+`POST /v2/Products/Variants/Table`
+
+```json
+{
+  "search": {
+    "productId": "example-product"
+  },
+  "attributeCode": "Voltage",
+  "attributeCodes": ["CatalogNumber"],
+  "appSettings": {
+    "appCode": "example"
+  }
+}
+```
+
+The response is a `ProductVariantsTableSearchResultV2` wrapper containing exactly one full item:
+
+```json
+{
+  "items": [
+    {
+      "attributeCode": "Voltage",
+      "attributeName": "Voltage",
+      "attributeValueText": "230 V",
+      "variantAttributes": [],
+      "products": []
+    }
+  ]
+}
+```
+
+`attributeCode` is required and must identify a visible variant group available for the requested product and
+application context. Empty, unknown, unavailable, or inaccessible codes return `400 Bad Request`. The endpoint uses
+the same application filters, country and tenant context, internal-data visibility, authorization, and short-lived
+output caching as the Detail variant query. `attributeCodes` controls additional serialized attributes on returned
+variant products.
+
+### Client Migration
+
+1. Request `ProductVariantsTable` from v2 Detail.
+2. Render the first full group and retain metadata for the remaining groups.
+3. Call `POST /v2/Products/Variants/Table` with the selected `attributeCode` when another group is needed.
+4. Replace the sparse group with the returned full group.
+
+An equivalent v2 Dropdown action is not part of this change and may be added separately in the `Variants` controller.
+
+### Compatibility and Validation
+
+- V1 Detail behavior and DTOs are unchanged.
+- V2 Detail changes only the `ProductVariantsTable` response shape when that data type is requested.
+- Selector and Dropdown response sections keep their existing behavior.
+- The new endpoint is v2-only and uses the standard v2 authorization, validation, error, logging, and cache pipeline.
+- The new endpoint does not add pagination; the returned group may contain all matching variant products.
+
+## Filters and Filter Values
+
+V2 separates filter discovery from loading selectable values. This reduces the response size of product Search and
+allows clients to request values only for filters that are currently expanded or otherwise needed.
+
+- `POST /v2/Products/Filters` returns available filter metadata without `values`.
+- `POST /v2/Products/FilterValues` returns values for the selected `search.attributeCodes`.
+- `POST /v2/Products/RelationshipFilters` returns available relationship filter metadata without `values`.
+- `POST /v2/Products/RelationshipFilterValues` returns values for selected relationship filters.
+- `POST /v2/Products/Search` returns metadata without `values` in `filters` when `dataTypes` contains `Filters`.
+- `POST /v2/Catalogs/Products/Filters` returns available catalog filter metadata without `values`.
+- `POST /v2/Catalogs/Products/FilterValues` returns criterion-ready values for selected catalog filters.
+
+### v1
+
+The v1 `Products/Filters` and `Products/RelationshipFilters` endpoints continue to accept attribute codes under
+`search.attributeCodes` and return `FilterValueSearchResult`. Each filter contains its selectable `values`, exposes
+both deprecated `isPromoted` and replacement `promoted`, and uses `name` plus an optional `code` for each value:
+
+```json
+{
+  "items": [
+    {
+      "attributeCode": "Color",
+      "attributeName": "Color",
+      "attributeNameHtml": "Color",
+      "hitCount": 42,
+      "isPromoted": true,
+      "promoted": true,
+      "internal": false,
+      "values": [
+        {
+          "name": "Red",
+          "code": "RD",
+          "hitCount": 17
+        }
+      ]
+    }
+  ]
+}
+```
+
+For ordinary text attributes, `code` can be absent or null and `name` contains the value to filter by. For
+enumerations, `name` is localized display text and `code` is the criterion value. For multidimensional attributes,
+`name` is formatted display text and `code` contains the encoded source value.
+
+### v2 Filter Discovery
+
+Use `Products/Filters` or `Catalogs/Products/Filters` to retrieve product filter metadata:
+
+```json
+{
+  "search": {
+    "cid": "Root"
+  },
+  "filters": {
+    "attributeCodes": ["Color", "Voltage"]
+  },
+  "appSettings": {
+    "appCode": "example"
+  }
+}
+```
+
+`filters.attributeCodes` is optional. When supplied, it selects the metadata to return and overrides the
+default AGM parametric or predefined filter list. The response contains no selectable values:
+
+```json
+{
+  "items": [
+    {
+      "attributeCode": "Color",
+      "attributeName": "Color",
+      "attributeNameHtml": "Color",
+      "hitCount": 42,
+      "promoted": true,
+      "internal": false
+    }
+  ],
+  "totalCount": 12
+}
+```
+
+`totalCount` is the number of available filters before optional response limiting. The same metadata-only shape is
+used by `SearchResult.filters` and the v2 `RelationshipFilters` response. V2 omits obsolete `isPromoted`.
+
+For `POST /v2/Products/Search`, optional top-level `filterSettings` is effective only when `dataTypes` contains
+`Filters`:
+
+```json
+{
+  "dataTypes": ["Products", "Filters"],
+  "filterSettings": {
+    "maxFilterAttributes": 10,
+    "attributeCodes": ["Color", "Voltage"]
+  },
+  "appSettings": {
+    "appCode": "example"
+  }
+}
+```
+
+V2 Search requires `dataTypes` to contain at least one value. Omitting it, sending `null`, or sending an empty array
+returns `400`. Clients should request only the response sections they consume; v1 Search validation remains
+unchanged.
+
+`maxFilterAttributes` limits non-promoted filters. Promoted filters are not limited unless explicit
+`attributeCodes` are supplied.
+
+### v2 Filter Values
+
+Use `Products/FilterValues` or `Catalogs/Products/FilterValues` to retrieve values for selected product filters.
+For both endpoints, `search.attributeCodes` is required,
+must be non-empty, accepts at most 100 codes, and every code must be non-empty:
+
+```json
+{
+  "search": {
+    "cid": "Root",
+    "attributeCodes": ["Color"]
+  },
+  "appSettings": {
+    "appCode": "example"
+  }
+}
+```
+
+The response uses `FilterValueSearchResultV2`. Each selectable value replaces v1 `name` and `code` with `text` and a
+required criterion-ready `CriterionValue` object:
+
+```json
+{
+  "items": [
+    {
+      "attributeCode": "Color",
+      "attributeName": "Color",
+      "attributeNameHtml": "Color",
+      "hitCount": 42,
+      "promoted": true,
+      "internal": false,
+      "values": [
+        {
+          "text": "Red",
+          "value": { "V": "RD" },
+          "hitCount": 17
+        }
+      ]
+    }
+  ]
+}
+```
+
+For ordinary text and table attributes, `text` is the display text and `value.V` contains the same raw facet value.
+For enumerations, `text` is the localized label and `value.V` contains the enumeration code. Multidimensional values
+are returned without their legacy encoded representation:
+
+```json
+{
+  "text": "50 mm",
+  "value": {
+    "H": "",
+    "V": "50",
+    "U": "MM"
+  },
+  "hitCount": 8
+}
+```
+
+Relationship filters use the same split. `RelationshipFilters` accepts `PrmSearchSettings` plus optional
+`filters.attributeCodes`; `RelationshipFilterValues` accepts the relationship search fields and requires
+`search.attributeCodes`. Both preserve the PRM block-join facet domain and relationship-specific AGM ordering.
+
+### Client Migration
+
+1. Use `Filters` or `Search` with `dataTypes: ["Filters"]` to discover available filter metadata.
+2. When the client needs selectable product or catalog values, call the corresponding `FilterValues` endpoint with those codes in `search.attributeCodes`.
+3. Apply the same flow to `RelationshipFilters` and `RelationshipFilterValues` for PRM results.
+4. Read display text from `values[].text` and pass `values[].value` directly to a v2 attribute criterion.
+5. Preserve all returned `H`, `V`, and `U` fields for multidimensional filters; do not parse display text.
+6. Read only `promoted`; obsolete `isPromoted` is not present in v2 responses.
+
+### Compatibility and Validation
+
+- V1 `Filters` and `RelationshipFilters` routes, requests, and `FilterValueSearchResult` responses are unchanged.
+- Sending a former v2 product or catalog `Filters` request with `search.attributeCodes` no longer requests values. The
+  unknown `attributeCodes` property under `search` is ignored by the current JSON configuration; use `filters`
+  for metadata selection or the corresponding `FilterValues` endpoint for values.
+- V2 `FilterValues`, `RelationshipFilterValues`, and catalog `FilterValues` reject missing, null, empty, over-100, or
+  blank attribute-code selections.
+- Existing product search criteria and recursive `search.filter` criteria remain available on the product, relationship,
+  and catalog v2 filter endpoints.
+- Product matching, relationship matching, hit counts, localization, criterion-ready values, and HTTP status behavior
+  are unchanged.
+- `POST /v2/Catalogs/Products/Filters` returns metadata and `POST /v2/Catalogs/Products/FilterValues` returns values.
+- V2 OpenAPI exposes `FilterSearchResult` for discovery and `FilterValueSearchResult`, `FilterValueItem`, and
+  `FilterValue` for value responses after the global v2 schema-name rule removes implementation suffixes.
+- Relationship v1 service tests cover the compatibility path; focused v2 response-contract tests remain pending.
+
+## Interactive Guides
+
+The v2 OpenAPI document omits `InteractiveGuides` from `SearchDataTypeEnum` and `DetailDataTypeEnum`. It also omits
+the obsolete `interactiveGuides` response properties from Search and Detail responses. The v1 OpenAPI document
+continues to expose these enum values and response properties for backward compatibility.
+
+Clients migrating to `POST /v2/Products/Search` or `POST /v2/Products/Detail` must stop including
+`"InteractiveGuides"` in `dataTypes`. Interactive guides are no longer populated in responses.
+
+This is currently an OpenAPI contract change only. Because v1 and v2 share the underlying .NET enum types, the v2
+JSON converter can still deserialize `"InteractiveGuides"`; v2 validation does not reject it. Runtime rejection
+would require a separate validation change or dedicated v2 enum types.
+
+Verification confirms that the served v1 OpenAPI document retains `InteractiveGuides`, while the served v2 OpenAPI
+document contains no `InteractiveGuides` enum values, descriptions, or response properties.
+
+## OpenAPI Schema Names
+
+The v2 OpenAPI document removes the trailing `V2` suffix from component schema names. This keeps implementation
+versioning details out of the public model names displayed by Scalar and consumed by OpenAPI client generators.
+
+The rule has no collision exceptions. Version-specific Compare and Favorite Views responses ensure that legacy
+`AttributeGroup` and `SearchSettings` schemas are not referenced by v2 operations. Their v2 counterparts are exposed
+as `AttributeGroup` and `SearchSettings` in the v2 document.
+
+Polymorphic types derived from `Criterion` also use their direct type names. The v2 component schemas are exposed as
+`AttributeCriterion` and `CriteriaGroup`, rather than the default concatenated names `CriterionAttributeCriterion`
+and `CriterionCriteriaGroup`. The base schema remains `Criterion`, and its discriminator mappings and `$ref` values
+point to the shortened component names.
+
+This change affects only schema keys under `components.schemas` and their `$ref` values in the v2 OpenAPI document.
+It does not rename C# types, JSON properties, routes, request or response payloads, or schemas in the v1 OpenAPI
+document. Clients regenerated from the v2 specification may receive model type renames even though their serialized
+JSON contracts are unchanged.
+
+## Translation Domains
+
+`POST /v2/Translations` replaces free-form component names with a fixed set of translation domains. The response
+uses the same domain enum and no longer exposes the legacy component property.
+
+### v1
+
+```json
+{
+  "components": ["products", "common"],
+  "appSettings": {
+    "appCode": "example"
+  }
+}
+```
+
+The v1 response continues to use a string `component`:
+
+```json
+[
+  {
+    "component": "products",
+    "key": "Product.Title",
+    "value": "Product"
+  }
+]
+```
+
+### v2
+
+```json
+{
+  "domains": ["Products", "Common"],
+  "appSettings": {
+    "appCode": "example"
+  }
+}
+```
+
+`domains` accepts only `Catalogs`, `Classifications`, `Common`, and `Products`. If it is omitted, null, or empty,
+translations from all four supported domains are returned.
+
+The v2 response uses `TranslationItemV2`, where `domain` is the same enum:
+
+```json
+[
+  {
+    "domain": "Products",
+    "key": "Product.Title",
+    "value": "Product"
+  }
+]
+```
+
+### Client Migration
+
+1. Replace `components` with `domains` in v2 translation requests.
+2. Change lowercase free-form component strings to the corresponding enum names.
+3. Read `domain` instead of `component` from each v2 response item.
+
+### Compatibility and Validation
+
+- The v1 request and response contracts are unchanged.
+- A v2 payload containing legacy `components` is accepted by the current JSON configuration, but the unknown
+  property is ignored; omitting `domains` therefore returns all supported domains.
+- Values outside the four declared domains are rejected during v2 request binding.
+- Translation lookup, language fallback, output caching, and HTTP status behavior are unchanged.
+- The v2 OpenAPI operation exposes enum-based `domains` in the request and enum-based `domain` in its response.
+
+## Query-Scoped Relationship and Variant Settings
+
+V2 no longer exposes `productRelationshipFiltering` or `variant` inside `appSettings`. These options describe the
+result of the current query, so they are now scoped to the query that uses them. The v1 `AppSettings` contract and all
+v1 behavior remain unchanged.
+
+`variants` uses `VariantSettingsV2`:
+
+```json
+{
+  "variants": {
+    "clustering": true,
+    "attributeCodes": ["Color", "Voltage_*"]
+  }
+}
+```
+
+`clustering` controls the Solr variant collapse for product search results, counts, filter metadata, filter values,
+and autocomplete. `attributeCodes` requests additional serialized product attributes. In `Detail`, it applies to the
+variant products returned by the selected variant data types.
+
+`relationships` uses `RelationshipSettingsV2`:
+
+```json
+{
+  "relationships": {
+    "productRelationshipFiltering": true,
+    "attributeCodes": ["RelationshipAttribute", "Voltage_*"],
+    "pager": {
+      "page": 1,
+      "pageSize": 20
+    }
+  }
+}
+```
+
+The relationship settings control relationship filter metadata, additional attributes for related products, and public
+pagination of relationship products. In `Detail`, the existing internal `relationshipPager` is replaced by the public
+`relationships.pager`. `PrmQueryV2` and `PrmAutocompleteQueryV2` likewise use `relationships.pager`; their former
+top-level v2 pager is no longer used. `PrmQueryV2` also places relationship attribute selection under
+`relationships.attributeCodes`.
+
+The query coverage is:
+
+| Setting         | v2 query contracts                                                                                                                           |
+| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `variants`      | `SearchQueryV2`, `AutocompleteQueryV2`, `CountQueryV2`, `FiltersQueryV2`, `FilterValueQueryV2`, `DetailQueryV2`, and `ClassificationQueryV2` |
+| `relationships` | `DetailQueryV2`, `PrmQueryV2`, `PrmFiltersQueryV2`, `PrmFilterValueQueryV2`, and `PrmAutocompleteQueryV2`                                    |
+
+Legacy v2 payloads that still put these properties under `appSettings` are not transformed; the old properties are
+unknown to `AppSettingsV2` and are ignored by JSON binding. Clients must move them to the query-level sections above.
+
+## Query-Scoped Attribute Sorting
+
+V2 attribute sort mappings are no longer supplied through `appSettings.sort`. The v2 `SearchQuery` and
+`PriceListQuery` contracts expose `SortSettingsV2`, which combines the regular field/direction sort with optional
+attribute mappings:
+
+```json
+{
+  "sort": {
+    "field": "Relevance",
+    "direction": "Descending",
+    "map": [
+      {
+        "attributeCode": "ProductStatus",
+        "values": ["Preferred", "Standard"]
+      }
+    ]
+  },
+  "appSettings": {
+    "appCode": "example"
+  }
+}
+```
+
+`sort.map` is supported by `SearchQueryV2` and `PriceListQueryV2` only. The map is applied to the Solr request for
+the current query. `Count`, `Filters`, `FilterValues`, `Detail`, autocomplete, and relationship queries do not accept
+this setting. The v1 `AppSettings.Sort` contract remains unchanged.
+
+## Endpoint Rollout
+
+| Endpoint                                                         | v2 request contract                                                                                  | Filter execution                                                                                               | Status      |
+| ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | ----------- |
+| `POST /v2/Translations`                                          | `TranslationQuery` with enum-based `Domains` and `TranslationItem` response with enum-based `Domain` | Not applicable                                                                                                 | Implemented |
+| `POST /v2/Sitemap/Products`                                      | `SitemapProductSearchQuery` with `AppSettings`; `SitemapProductSearchSettings` is unchanged          | Flat scalar `Criteria` is mapped to the v1 Solr filter path; nested and multidimensional criteria return `400` | Implemented |
+| `POST /v2/Products/Search`                                       | `SearchQuery` with optional `filterSettings` when `dataTypes` contains `Filters`                     | Returns filter metadata only; requested codes and maximum count can reduce the filter response                 | Implemented |
+| `POST /v2/Catalogs/Products/Search`                              | `CatalogProductSearchQueryV2` with optional `filterSettings` when `dataTypes` contains `Filters`     | Returns catalog filter metadata with the requested codes and maximum count applied                             | Implemented |
+| `POST /v2/Products/Filters`                                      | `FiltersQuery` with optional search and metadata `filters`                                           | Returns available `FilterSearchResult` metadata without selectable values                                      | Implemented |
+| `POST /v2/Products/FilterValues`                                 | `FilterValueQuery` with required `search.attributeCodes`                                             | Returns criterion-ready `FilterValueSearchResult` values for selected attributes                               | Implemented |
+| `POST /v2/Products/RelationshipFilters`                          | `PrmFiltersQuery` with optional metadata `filters`                                                   | Returns relationship filter metadata using the PRM block-join domain                                           | Implemented |
+| `POST /v2/Products/RelationshipFilterValues`                     | `PrmFilterValueQuery` with required `search.attributeCodes`                                          | Returns criterion-ready relationship filter values using the PRM block-join domain                             | Implemented |
+| `POST /v2/Catalogs/Products/Filters`                             | `CatalogProductFiltersQueryV2` with optional metadata `filters`                                      | Returns catalog product filter metadata                                                                        | Implemented |
+| `POST /v2/Catalogs/Products/FilterValues`                        | `CatalogProductFilterValuesQueryV2` with required `search.attributeCodes`                            | Returns criterion-ready catalog filter values                                                                  | Implemented |
+| Product search, count, list, autocomplete, and related endpoints | To be added                                                                                          | Pending `Criteria` query compilation                                                                           | Not started |
+
+## Update Checklist
+
+When adding the next v2 migration item:
+
+1. Add the v1 and v2 JSON examples.
+2. State whether legacy input is ignored, rejected, or transformed.
+3. Identify endpoint coverage and response impact.
+4. Add validation, service, query-composition, cache, and OpenAPI status.
+5. Add focused tests and update the change-log status.