Add API Resource Integration Aspect Subset (#66)

Author: Fannon

CHANGELOG.md

@@ -20,6 +20,9 @@ For a roadmap including expected timeline, please refer to [ROADMAP.md](./ROADMA
   - Added example A2A agent card definition [DisputeResolutionAgentcard.json](examples/definitions/DisputeResolutionAgentcard.json)
   - Added [AI Agents and Protocols](docs/spec-v1/concepts/ai-agents-and-protocols.md) concept documentation
 - Introduced `abstract` property for API, Event and Data Product Resources to indicate interface-only resources.
+- Added `subset` property to `ApiResourceIntegrationAspect` with new `ApiResourceIntegrationAspectSubset` definition
+  - This allows narrowing down API resource integration aspects to specific operations or tools
+  - The `operationId` field can be used to specify individual API operations (e.g., OpenAPI `operationId`) or tools (e.g., MCP tool `name`)
 - Added `labels` and `correlationIds` to group and group type.
   - This allows to apply extensions / references to non ORD concepts via IDs, making the group concept more extensible.
 

examples/documents/document-integration-dependencies.jsonc

@@ -116,6 +116,15 @@
             {
               "ordId": "sap.cic:apiResource:RetailTransactionOData:v1",
               "minVersion": "1.3.0",
+              // The subset property allows narrowing down to specific API operations
+              "subset": [
+                {
+                  "operationId": "getRetailTransactions"
+                },
+                {
+                  "operationId": "getRetailTransactionById"
+                }
+              ]
             },
             {
               "ordId": "sap.cic:apiResource:RetailTransactionSQL:v2",

spec/v1/Document.schema.yaml

@@ -3393,13 +3393,20 @@ definitions:
         description: |
           Minimum version of the references resource that the integration requires.
 
+      subset:
+        type: array
+        description: |-
+          List of individual API operations that are sufficient to achieve the aspect.
+        items:
+          $ref: "#/definitions/ApiResourceIntegrationAspectSubset"
+
       # consumptionBundleRestriction: &consumptionBundleRestriction
       #   type: array
       #   description: |-
       #     Within the context of the Integration Dependency, there can be constraints which Consumption Bundles to use.
       #   items:
       #     type: string
-      #     pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(consumptionBundle):([a-zA-Z0-9._\-]+):(alpha|beta|v[0-9]+|)$
+      #     pattern: ^([a-z0-9]+(?:[.][a-z0-9]+]*):(consumptionBundle):([a-zA-Z0-9._\-]+):(alpha|beta|v[0-9]+|)$
       #   examples:
       #     - ['sap.foo:consumptionBundle:basicAuth:v1']
 
@@ -3483,6 +3490,32 @@ definitions:
     required:
       - eventType
 
+  ApiResourceIntegrationAspectSubset:
+    type: object
+    title: API Resource Integration Aspect Subset
+    x-introduced-in-version: "1.10.0"
+    x-ums-type: "custom"
+    description: |-
+      Defines that API Resource Integration Aspect only requires a subset of the referenced contract.
+
+      For APIs, this is a list of the operations or tools that need to be available in order to make the integration work.
+      This information helps to narrow down what is really necessary and can help optimize the integration.
+    properties:
+      operationId:
+        type: string
+        description: |-
+          The ID of the individual API operation or tool.
+
+          This MUST be an ID that is understood by the used protocol and resource definition format.
+          E.g. for OpenAPI this is the `operationId`, for MCP this is the tool `name`.
+        examples:
+          - "getOrderById"
+          - "createCustomer"
+
+    additionalProperties: false
+    required:
+      - operationId
+
   Vendor:
     type: object
     title: Vendor

src/generated/spec/v1/types/Document.ts

@@ -3099,6 +3099,25 @@ export interface ApiResourceIntegrationAspect {
    *
    */
   minVersion?: string;
+  /**
+   * List of individual API operations that are sufficient to achieve the aspect.
+   */
+  subset?: APIResourceIntegrationAspectSubset[];
+}
+/**
+ * Defines that API Resource Integration Aspect only requires a subset of the referenced contract.
+ *
+ * For APIs, this is a list of the operations or tools that need to be available in order to make the integration work.
+ * This information helps to narrow down what is really necessary and can help optimize the integration.
+ */
+export interface APIResourceIntegrationAspectSubset {
+  /**
+   * The ID of the individual API operation or tool.
+   *
+   * This MUST be an ID that is understood by the used protocol and resource definition format.
+   * E.g. for OpenAPI this is the `operationId`, for MCP this is the tool `name`.
+   */
+  operationId: string;
 }
 /**
  * Event resource related integration aspect

static/spec-v1/interfaces/Document.schema.json

@@ -5116,6 +5116,13 @@
             "1.2.3",
             "1.0.0-alpha.1"
           ]
+        },
+        "subset": {
+          "type": "array",
+          "description": "List of individual API operations that are sufficient to achieve the aspect.",
+          "items": {
+            "$ref": "#/definitions/ApiResourceIntegrationAspectSubset"
+          }
         }
       },
       "additionalProperties": false,
@@ -5196,6 +5203,27 @@
         "eventType"
       ]
     },
+    "ApiResourceIntegrationAspectSubset": {
+      "type": "object",
+      "title": "API Resource Integration Aspect Subset",
+      "x-introduced-in-version": "1.10.0",
+      "x-ums-type": "custom",
+      "description": "Defines that API Resource Integration Aspect only requires a subset of the referenced contract.\n\nFor APIs, this is a list of the operations or tools that need to be available in order to make the integration work.\nThis information helps to narrow down what is really necessary and can help optimize the integration.",
+      "properties": {
+        "operationId": {
+          "type": "string",
+          "description": "The ID of the individual API operation or tool.\n\nThis MUST be an ID that is understood by the used protocol and resource definition format.\nE.g. for OpenAPI this is the `operationId`, for MCP this is the tool `name`.",
+          "examples": [
+            "getOrderById",
+            "createCustomer"
+          ]
+        }
+      },
+      "additionalProperties": false,
+      "required": [
+        "operationId"
+      ]
+    },
     "Vendor": {
       "type": "object",
       "title": "Vendor",

static/spec-v1/interfaces/ums/MetadataType/integrationdependency.yaml

@@ -162,6 +162,17 @@ spec:
           description: "Minimum version of the references resource that the integration requires.\n"
           constraints:
             pattern: '^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$'
+        - name: 'subset'
+          type: 'custom'
+          customTypeName: 'ApiResourceIntegrationAspectSubset'
+          array: true
+          description: 'List of individual API operations that are sufficient to achieve the aspect.'
+    - name: 'ApiResourceIntegrationAspectSubset'
+      metadataProperties:
+        - name: 'operationId'
+          type: 'string'
+          description: "The ID of the individual API operation or tool.\n\nThis MUST be an ID that is understood by the used protocol and resource definition format.\nE.g. for OpenAPI this is the `operationId`, for MCP this is the tool `name`."
+          mandatory: true
     - name: 'EventResourceIntegrationAspect'
       metadataProperties:
         - name: 'ordId'