Enhance round-trip comparison by refining ignored properties for API imports

Author: EMaher

.squad/agents/apimexpert/history.md

@@ -106,3 +106,13 @@ the SDK surface, reference docs, or ad-hoc observation.
 - Classic Developer/Premium SKU only.
 - Docs: <https://learn.microsoft.com/rest/api/apimanagement/policy-restriction> · <https://learn.microsoft.com/azure/templates/microsoft.apimanagement/service/policyrestrictions>
 
+### 2026-06-20: Link-import vs inline-import operation fidelity (round-trip)
+
+When comparing a *link-imported* API (e.g. Petstore via `swagger-link`/`openapi-link`) against the `apiops publish` *inline-imported* result, operation payloads diverge in two import-path-only ways — neither is an apiops bug:
+
+1. **`schemaId`/`typeName` on representations.** APIM binds operation request/response representations to an API-level schema **only on link import**. Inline import (`format: openapi, value: <spec>`, what publish uses) does NOT rebind, so the target has no `schemaId`. The schema *content* is identical and still extracted as API-level Schemas. → strip `schemaId`, `typeName` (and any derived schema token) on operation resources.
+
+2. **Parameter/header `description`.** Link import drops `templateParameters`/`queryParameters`/header descriptions; inline import preserves them from the spec. So the published **target is more faithful** than the link-imported source. Authoritative descriptions live in the API schema. → strip `description` on parameter-shaped objects (`{ name, …, values }`).
+
+Round-trip comparison harness (`tests/integration/all-resource-types`) normalizes both via `RepresentationSchemaRefIgnoredProperties` and `ParameterIgnoredProperties`. Symptom if not stripped: every operation shows a `properties.request/responses/templateParameters` DIFF present-on-one-side-only.
+

tests/integration/all-resource-types/Compare-ApimInstance.ps1

@@ -58,12 +58,19 @@ $StripTimestampProperties = @(
 $RequestResponseIgnoredProperties = @('description')
 
 # Properties ignored on representation objects (have 'contentType' or 'schemaId'):
-# - description: SOAP/WSDL import generates descriptions that vary
-# - schemaId/typeName: Operation reconciliation strips these before PATCH because
-#   APIM rebinds representation schema refs during import. Values are therefore
-#   not stable for round-trip comparison and are ignored for operation resources.
+# - description: varies by import path.
+# - schemaId/typeName: unstable schema refs APIM rebinds on import; stripped for ops.
+# - __schemaSemantic: synthetic token from Add-RepresentationSchemaSemantics. Only
+#   link-imported source gets schemaId (and thus this token); inline-imported target
+#   doesn't. Schema content is compared separately via API-level Schemas, so strip it.
 $RepresentationIgnoredProperties = @('description')
-$RepresentationSchemaRefIgnoredProperties = @('schemaId', 'typeName')
+$RepresentationSchemaRefIgnoredProperties = @('schemaId', 'typeName', '__schemaSemantic')
+
+# Properties ignored on parameter/header objects (have 'name' + 'values':
+# templateParameters, queryParameters, response headers):
+# - description: link import (source) drops them; inline import (target) keeps them.
+#   Authoritative copies live in the API schema, compared separately.
+$ParameterIgnoredProperties = @('description')
 
 # Cache of normalized API schema semantics per instance/api, keyed as:
 # "{instance}|{apiName}" => @{ schemaId => normalizedSchemaJson }
@@ -78,7 +85,8 @@ $NormalizationContext = New-CompareNormalizationContext `
     -StripTimestampProperties $StripTimestampProperties `
     -RequestResponseIgnoredProperties $RequestResponseIgnoredProperties `
     -RepresentationIgnoredProperties $RepresentationIgnoredProperties `
-    -RepresentationSchemaRefIgnoredProperties $RepresentationSchemaRefIgnoredProperties
+    -RepresentationSchemaRefIgnoredProperties $RepresentationSchemaRefIgnoredProperties `
+    -ParameterIgnoredProperties $ParameterIgnoredProperties
 
 # ── Helpers ─────────────────────────────────────────────────────────────────
 

tests/integration/all-resource-types/modules/CompareSemantics.psm1

@@ -194,7 +194,8 @@ function New-CompareNormalizationContext {
         [string[]] $StripTimestampProperties = @(),
         [string[]] $RequestResponseIgnoredProperties = @(),
         [string[]] $RepresentationIgnoredProperties = @(),
-        [string[]] $RepresentationSchemaRefIgnoredProperties = @()
+        [string[]] $RepresentationSchemaRefIgnoredProperties = @(),
+        [string[]] $ParameterIgnoredProperties = @()
     )
 
     return [ordered]@{
@@ -210,6 +211,7 @@ function New-CompareNormalizationContext {
         RequestResponseIgnoredProperties = $RequestResponseIgnoredProperties
         RepresentationIgnoredProperties = $RepresentationIgnoredProperties
         RepresentationSchemaRefIgnoredProperties = $RepresentationSchemaRefIgnoredProperties
+        ParameterIgnoredProperties = $ParameterIgnoredProperties
     }
 }
 
@@ -266,12 +268,18 @@ function ConvertTo-NormalizedPropertyValue {
         $out = [ordered]@{}
         $isRequestResponse = $Value.Contains('representations')
         $isRepresentation = $Value.Contains('contentType') -or $Value.Contains('schemaId')
+        # Parameter/header objects (templateParameters, queryParameters, response
+        # headers) are shaped as { name, type, values, ... } with no representations
+        # and no contentType/schemaId.
+        $isParameter = (-not $isRequestResponse) -and (-not $isRepresentation) -and `
+            $Value.Contains('name') -and $Value.Contains('values')
         foreach ($key in ($Value.Keys | Sort-Object)) {
             if ($IsRoot -and $key -in $Context.StripReadOnlyProperties) { continue }
             if ($key -in $Context.StripTimestampProperties) { continue }
             if ($isRequestResponse -and $key -in $Context.RequestResponseIgnoredProperties) { continue }
             if ($isRepresentation -and $key -in $Context.RepresentationIgnoredProperties) { continue }
             if ($IgnoreRepresentationSchemaRefs -and $isRepresentation -and $key -in $Context.RepresentationSchemaRefIgnoredProperties) { continue }
+            if ($isParameter -and $key -in $Context.ParameterIgnoredProperties) { continue }
             $out[$key] = ConvertTo-NormalizedPropertyValue -Value $Value[$key] -Context $Context -IgnoreRepresentationSchemaRefs:$IgnoreRepresentationSchemaRefs
         }
         return $out
@@ -281,12 +289,19 @@ function ConvertTo-NormalizedPropertyValue {
         $out = [ordered]@{}
         $isRequestResponse = $null -ne ($Value.PSObject.Properties | Where-Object { $_.Name -eq 'representations' })
         $isRepresentation = $null -ne ($Value.PSObject.Properties | Where-Object { $_.Name -eq 'contentType' -or $_.Name -eq 'schemaId' })
+        # Parameter/header objects (templateParameters, queryParameters, response
+        # headers) are shaped as { name, type, values, ... } with no representations
+        # and no contentType/schemaId.
+        $hasName = $null -ne ($Value.PSObject.Properties | Where-Object { $_.Name -eq 'name' })
+        $hasValues = $null -ne ($Value.PSObject.Properties | Where-Object { $_.Name -eq 'values' })
+        $isParameter = (-not $isRequestResponse) -and (-not $isRepresentation) -and $hasName -and $hasValues
         foreach ($prop in ($Value.PSObject.Properties | Sort-Object Name)) {
             if ($IsRoot -and $prop.Name -in $Context.StripReadOnlyProperties) { continue }
             if ($prop.Name -in $Context.StripTimestampProperties) { continue }
             if ($isRequestResponse -and $prop.Name -in $Context.RequestResponseIgnoredProperties) { continue }
             if ($isRepresentation -and $prop.Name -in $Context.RepresentationIgnoredProperties) { continue }
             if ($IgnoreRepresentationSchemaRefs -and $isRepresentation -and $prop.Name -in $Context.RepresentationSchemaRefIgnoredProperties) { continue }
+            if ($isParameter -and $prop.Name -in $Context.ParameterIgnoredProperties) { continue }
             $out[$prop.Name] = ConvertTo-NormalizedPropertyValue -Value $prop.Value -Context $Context -IgnoreRepresentationSchemaRefs:$IgnoreRepresentationSchemaRefs
         }
         return $out