Make ApiOperation a first-class persisted resource with PATCH reconciliation

- Add operationInformation.json infoFile to ApiOperation resource type
- Add patchResource to IApimClient interface and ApimClient implementation
- Replace filterOperationsWithSchemaRefs workaround with unified PATCH reconciliation
  after spec import; removes commitId-gated branch
- Update unit tests to reflect new PATCH behavior
- Update documentation for ApiOperation artifact format

Author: Copilot

docs/reference/artifact-format.md

@@ -143,7 +143,7 @@ All 34 APIM resource types and their artifact mappings:
 | ApiPolicy | `apis/{api}` | `policy.xml` |
 | ApiTag | `apis/{api}/tags/{tag}` | `tagInformation.json` |
 | ApiDiagnostic | `apis/{api}/diagnostics/{diagnostic}` | `diagnosticInformation.json` |
-| ApiOperation | `apis/{api}/operations/{operation}` | _(none)_ |
+| ApiOperation | `apis/{api}/operations/{operation}` | `operationInformation.json` |
 | ApiOperationPolicy | `apis/{api}/operations/{operation}` | `policy.xml` |
 | ApiSchema | `apis/{api}/schemas/{schema}` | `schemaInformation.json` |
 | ApiRelease | `apis/{api}/releases/{release}` | `releaseInformation.json` |

docs/reference/resource-types.md

@@ -59,7 +59,7 @@ Resources scoped to a specific API.
 | ApiPolicy | `/apis/{name}/policies/policy` | `apis/{0}` | `policy.xml` | Policy applied to all operations in an API |
 | ApiTag | `/apis/{name}/tags/{tag}` | `apis/{0}/tags/{1}` | `tagInformation.json` | Tag applied to an API |
 | ApiDiagnostic | `/apis/{name}/diagnostics/{diag}` | `apis/{0}/diagnostics/{1}` | `diagnosticInformation.json` | Diagnostic settings scoped to an API |
-| ApiOperation | `/apis/{name}/operations/{op}` | `apis/{0}/operations/{1}` | *(none)* | Individual API operation (GET /users, POST /orders, etc.) |
+| ApiOperation | `/apis/{name}/operations/{op}` | `apis/{0}/operations/{1}` | `operationInformation.json` | Individual API operation (GET /users, POST /orders, etc.) |
 | ApiOperationPolicy | `/apis/{name}/operations/{op}/policies/policy` | `apis/{0}/operations/{1}` | `policy.xml` | Policy applied to a specific API operation |
 | ApiSchema | `/apis/{name}/schemas/{schema}` | `apis/{0}/schemas/{1}` | `schemaInformation.json` | Schema definition for request/response validation |
 | ApiRelease | `/apis/{name}/releases/{release}` | `apis/{0}/releases/{1}` | `releaseInformation.json` | API release record (makes a revision current) |

src/clients/apim-client.ts

@@ -375,6 +375,30 @@ export class ApimClient implements IApimClient {
     }
   }
 
+  async patchResource(
+    context: ApimServiceContext,
+    descriptor: ResourceDescriptor,
+    payload: Record<string, unknown>
+  ): Promise<Record<string, unknown>> {
+    const url = buildArmUri(context, descriptor);
+
+    const response = await this.request(url, {
+      method: 'PATCH',
+      body: JSON.stringify(payload),
+    });
+
+    const responseText = await response.text();
+    if (!responseText.trim()) {
+      return {};
+    }
+
+    try {
+      return JSON.parse(responseText) as Record<string, unknown>;
+    } catch {
+      throw new SyntaxError(`Non-JSON response from APIM PATCH ${url}: ${responseText.substring(0, 200)}`);
+    }
+  }
+
   async deleteResource(
     context: ApimServiceContext,
     descriptor: ResourceDescriptor

src/clients/iapim-client.ts

@@ -39,6 +39,17 @@ export interface IApimClient {
     payload: Record<string, unknown>
   ): Promise<Record<string, unknown>>;
 
+  /**
+   * Partially update a resource (PATCH).
+   * Only the properties present in the payload are updated.
+   * Returns the response JSON body.
+   */
+  patchResource(
+    context: ApimServiceContext,
+    descriptor: ResourceDescriptor,
+    payload: Record<string, unknown>
+  ): Promise<Record<string, unknown>>;
+
   /**
    * Delete a resource (DELETE).
    * Returns true if deleted, false if already absent (404).

src/models/resource-types.ts

@@ -204,7 +204,7 @@ export const RESOURCE_TYPE_METADATA: Record<ResourceType, ResourceTypeMetadata>
   [ResourceType.ApiOperation]: {
     armPathSuffix: 'apis/{0}/operations/{1}',
     artifactDirectory: 'apis/{0}/operations/{1}',
-    infoFile: null,
+    infoFile: 'operationInformation.json',
     supportsGet: true,
   },
   [ResourceType.ApiOperationPolicy]: {

src/services/api-publisher.ts

@@ -265,11 +265,27 @@ async function publishApiRevisions(
   return sortedRevisions.length;
 }
 
+/**
+ * Properties allowed in operation PATCH bodies.
+ * Restricted to fields that are valid for all API types (HTTP, SOAP, GraphQL, WebSocket, A2A).
+ * Avoids sending fields APIM rejects on non-HTTP API types.
+ */
+const OPERATION_PATCH_ALLOWLIST: ReadonlySet<string> = new Set([
+  'displayName',
+  'description',
+  'method',
+  'urlTemplate',
+  'templateParameters',
+  'request',
+  'responses',
+  'policies',
+]);
+
 /**
  * Resource types that are auto-created by APIM when importing a spec.
  * Both ApiOperation and ApiSchema are initially excluded, but we selectively
- * re-add: operations with schema references, and explicitly named schemas
- * (non-auto-generated 24-char hex IDs).
+ * re-add: explicitly named schemas (non-auto-generated 24-char hex IDs).
+ * Operations are always reconciled via PATCH after spec import.
  */
 const SPEC_MANAGED_CHILD_TYPES = new Set<ResourceType>([
   ResourceType.ApiOperation,
@@ -280,7 +296,8 @@ const SPEC_MANAGED_CHILD_TYPES = new Set<ResourceType>([
  * Publish all child resources of an API in parallel.
  * When specImported is true, skips ApiSchema and ApiOperation since APIM
  * auto-creates those from the imported specification. However:
- * - Operations with schema references are re-PUT explicitly so APIM preserves those links
+ * - All operations are reconciled via PATCH after spec import to restore
+ *   persisted metadata (description, schema references, etc.)
  * - Explicitly named schemas (non-24-char-hex IDs) are also re-published
  */
 async function publishApiChildren(
@@ -302,40 +319,7 @@ async function publishApiChildren(
       !(specImported && SPEC_MANAGED_CHILD_TYPES.has(d.type))
   );
 
-  // When a spec was imported, APIM auto-creates operations and schemas but loses
-  // schemaId/typeName references in representations. Re-include operations that
-  // carry such references so those links are explicitly restored via PUT.
   if (specImported) {
-    // In incremental mode, avoid re-publishing operation artifacts after spec
-    // import. This prevents stale operation JSON from overwriting newly
-    // imported OpenAPI operation metadata (for example descriptions).
-    const shouldRepublishSchemaRefOps = !config.commitId;
-
-    const operationDescriptors = allDescriptors.filter(
-      (d) =>
-        d.type === ResourceType.ApiOperation &&
-        getNamePart(d.nameParts, 0) === getNamePart(apiDescriptor.nameParts, 0)
-    );
-
-    if (shouldRepublishSchemaRefOps) {
-      const schemaRefOps = await filterOperationsWithSchemaRefs(
-        store,
-        config.sourceDir,
-        operationDescriptors
-      );
-
-      if (schemaRefOps.length > 0) {
-        logger.debug(
-          `Re-publishing ${schemaRefOps.length} operation(s) with schema references after spec import for "${getNamePart(apiDescriptor.nameParts, 0)}"`
-        );
-        childDescriptors = [...childDescriptors, ...schemaRefOps];
-      }
-    } else {
-      logger.debug(
-        `Skipping schema-reference operation re-publish for "${getNamePart(apiDescriptor.nameParts, 0)}" in incremental mode`
-      );
-    }
-
     // Re-include explicitly named schemas (non-auto-generated IDs).
     // Auto-generated schemas have 24-char hex names and are recreated by spec import.
     // Explicitly named schemas (like "src-rest-schema-item") must be published.
@@ -377,67 +361,77 @@ async function publishApiChildren(
       await runParallel(tasks, 5);
     }
   }
-}
 
-/**
- * Returns the subset of operation descriptors whose stored artifact contains
- * at least one representation with a schemaId or typeName property.
- * These operations must be re-PUT after a spec import so APIM retains the
- * schema linkage that the import path discards.
- */
-async function filterOperationsWithSchemaRefs(
-  store: IArtifactStore,
-  sourceDir: string,
-  operationDescriptors: ResourceDescriptor[]
-): Promise<ResourceDescriptor[]> {
-  const result: ResourceDescriptor[] = [];
-
-  for (const descriptor of operationDescriptors) {
-    const json = await store.readResource(sourceDir, descriptor);
-    if (json && operationHasSchemaRefs(json)) {
-      result.push(descriptor);
-    }
+  // After spec import, reconcile all operations by PATCHing with persisted metadata.
+  // This ensures APIM retains the original operation state (description, schema refs, etc.)
+  // regardless of what the importer defaulted. PATCH is idempotent and only updates
+  // the fields present in the persisted JSON.
+  if (specImported) {
+    await reconcileOperationsAfterSpecImport(client, store, context, apiDescriptor, config, allDescriptors);
   }
-
-  return result;
 }
 
 /**
- * Returns true if the operation JSON contains at least one representation
- * (in request or any response) that has a schemaId or typeName property.
+ * Reconcile all API operations after a spec import by PATCHing each operation
+ * with its persisted metadata. Only allow-listed properties are sent in the
+ * PATCH body so APIM does not reject the request for non-HTTP API types.
+ *
+ * Skips operations with auto-generated IDs (24-char hex) — these are SOAP
+ * operations recreated by the WSDL importer; their persisted JSON, if any,
+ * should not override the importer's result.
  */
-function operationHasSchemaRefs(json: Record<string, unknown>): boolean {
-  const props = json.properties as Record<string, unknown> | undefined;
-  if (!props) return false;
+async function reconcileOperationsAfterSpecImport(
+  client: IApimClient,
+  store: IArtifactStore,
+  context: ApimServiceContext,
+  apiDescriptor: ResourceDescriptor,
+  config: PublishConfig,
+  allDescriptors: ResourceDescriptor[]
+): Promise<void> {
+  const operationDescriptors = allDescriptors.filter(
+    (d) =>
+      d.type === ResourceType.ApiOperation &&
+      getNamePart(d.nameParts, 0) === getNamePart(apiDescriptor.nameParts, 0) &&
+      !isAutoGeneratedId(getNamePart(d.nameParts, 1))
+  );
 
-  const representationGroups: unknown[] = [];
+  if (operationDescriptors.length === 0) return;
 
-  const request = props.request as Record<string, unknown> | undefined;
-  if (request?.representations) {
-    representationGroups.push(request.representations);
-  }
+  const tasks = operationDescriptors.map((descriptor) => async () => {
+    const json = await store.readResource(config.sourceDir, descriptor);
+    if (!json) return;
 
-  const responses = props.responses as unknown[] | undefined;
-  if (Array.isArray(responses)) {
-    for (const response of responses) {
-      const r = response as Record<string, unknown>;
-      if (r.representations) {
-        representationGroups.push(r.representations);
+    const props = json.properties as Record<string, unknown> | undefined;
+    if (!props) return;
+
+    // Build a PATCH body with only allow-listed properties present in the persisted JSON.
+    const patchProps: Record<string, unknown> = {};
+    for (const key of OPERATION_PATCH_ALLOWLIST) {
+      if (Object.hasOwn(props, key)) {
+        patchProps[key] = props[key];
       }
     }
-  }
 
-  for (const group of representationGroups) {
-    if (!Array.isArray(group)) continue;
-    for (const rep of group) {
-      const r = rep as Record<string, unknown>;
-      if (r.schemaId != null || r.typeName != null) {
-        return true;
-      }
+    if (Object.keys(patchProps).length === 0) return;
+
+    const patchBody: Record<string, unknown> = { properties: patchProps };
+
+    try {
+      await client.patchResource(context, descriptor, patchBody);
+      logger.debug(`Reconciled operation "${getNamePart(descriptor.nameParts, 1)}" after spec import`);
+    } catch (error) {
+      logger.warn(
+        `Failed to reconcile operation "${getNamePart(descriptor.nameParts, 1)}" after spec import: ${(error as Error).message}`
+      );
     }
-  }
+  });
 
-  return false;
+  if (tasks.length > 0) {
+    logger.debug(
+      `Reconciling ${tasks.length} operation(s) after spec import for "${getNamePart(apiDescriptor.nameParts, 0)}"`
+    );
+    await runParallel(tasks, 5);
+  }
 }
 
 /**

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

@@ -55,10 +55,10 @@ $RequestResponseIgnoredProperties = @('description')
 
 # Properties ignored on representation objects (have 'contentType' or 'schemaId'):
 # - description: SOAP/WSDL import generates descriptions that vary
-# - schemaId/typeName: When APIs are published via spec import (OpenAPI/Swagger),
-#   APIM recreates operations from the spec but does NOT populate schemaId/typeName
-#   in representations — the spec itself provides schema resolution. These fields
-#   appear in extracted artifacts but are absent after spec-based publish.
+# - schemaId/typeName: For SOAP APIs whose operations have auto-generated IDs,
+#   PATCH reconciliation is skipped and these fields may differ. For REST APIs,
+#   PATCH reconciliation restores them after spec import, so they should match.
+#   Kept here for SOAP compatibility.
 $RepresentationIgnoredProperties = @('description', 'schemaId', 'typeName')
 
 # ── Helpers ─────────────────────────────────────────────────────────────────

tests/unit/clients/artifact-store.test.ts

@@ -59,8 +59,8 @@ describe('ArtifactStore', () => {
 
     it('should handle types with no info file gracefully', async () => {
       const descriptor: ResourceDescriptor = {
-        type: ResourceType.ApiOperation,
-        nameParts: ['my-api', 'getUsers'],
+        type: ResourceType.ProductTag,
+        nameParts: ['my-product', 'my-tag'],
       };
 
       // writeResource should be a no-op

tests/unit/lib/resource-path.test.ts

@@ -128,13 +128,24 @@ describe('buildArtifactFilePath', () => {
     );
   });
 
-  it('should return undefined for types with no info file (ApiOperation)', () => {
+  it('should return undefined for types with no info file (ProductTag)', () => {
+    const descriptor: ResourceDescriptor = {
+      type: ResourceType.ProductTag,
+      nameParts: ['my-product', 'my-tag'],
+    };
+    const filePath = buildArtifactFilePath(baseDir, descriptor);
+    expect(filePath).toBeUndefined();
+  });
+
+  it('should return operationInformation.json path for ApiOperation', () => {
     const descriptor: ResourceDescriptor = {
       type: ResourceType.ApiOperation,
       nameParts: ['my-api', 'getUsers'],
     };
     const filePath = buildArtifactFilePath(baseDir, descriptor);
-    expect(filePath).toBeUndefined();
+    expect(filePath).toBe(
+      path.join(baseDir, 'apis', 'my-api', 'operations', 'getUsers', 'operationInformation.json')
+    );
   });
 
   it('should return policy.xml path for ServicePolicy', () => {
@@ -496,6 +507,7 @@ describe('buildArtifactFilePath + parseArtifactPath roundtrip for API child reso
     { type: ResourceType.ApiSchema, nameParts: ['my-api', 'my-schema'] },
     { type: ResourceType.ApiRelease, nameParts: ['my-api', 'my-release'] },
     { type: ResourceType.GraphQLResolver, nameParts: ['my-api', 'my-resolver'] },
+    { type: ResourceType.ApiOperation, nameParts: ['my-api', 'my-op'] },
     { type: ResourceType.ApiOperationPolicy, nameParts: ['my-api', 'my-op'] },
   ];