Application Research Capabilities API

openapi: 3.2.0
info:
  title: Application Research Open Resource Discovery (ORD) Capabilities API
  version: 1.12.0
  description: "The Open Resource Discovery (ORD) API provides access to ORD Documents which serve as wrappers \nfor ORD resources and taxonomy. This API enables discovery and management of API resources, \nevent resources, data products, entity types, capabilities, and integration dependencies.\n\nORD enables machine-readable self-description of systems and their capabilities, supporting\nautomated discovery, integration, and governance of enterprise APIs and services.\n"
  contact:
    name: ORD Specification Team
    url: https://open-resource-discovery.org
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://api.example.com/ord/v1
  description: Production server
- url: https://sandbox.example.com/ord/v1
  description: Sandbox server
security:
- oauth2:
  - ord:read
- bearerAuth: []
tags:
- name: Capabilities
  description: Capability operations
paths:
  /capabilities:
    get:
      tags:
      - Capabilities
      summary: Application Research List all Capabilities
      description: Retrieves a list of all Capabilities across all ORD Documents
      operationId: listCapabilities
      parameters:
      - $ref: '#/components/parameters/LimitParam'
      - $ref: '#/components/parameters/OffsetParam'
      - $ref: '#/components/parameters/CapabilityTypeFilterParam'
      responses:
        '200':
          description: Successfully retrieved list of Capabilities
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CapabilityList'
              examples:
                capabilityList:
                  $ref: '#/components/examples/CapabilityListExample'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /capabilities/{ordId}:
    get:
      tags:
      - Capabilities
      summary: Application Research Get a Capability by ORD ID
      description: Retrieves a specific Capability by its ORD ID
      operationId: getCapability
      parameters:
      - $ref: '#/components/parameters/CapabilityOrdIdParam'
      responses:
        '200':
          description: Successfully retrieved Capability
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Capability'
              examples:
                capability:
                  $ref: '#/components/examples/CapabilityExample'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    ReleaseStatus:
      type: string
      enum:
      - beta
      - active
      - deprecated
      - sunset
    Visibility:
      type: string
      enum:
      - public
      - internal
      - private
    SpecificationId:
      type: string
      pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$
      maxLength: 255
      description: Valid Specification ID
    Link:
      type: object
      title: Link
      required:
      - title
      - url
      properties:
        title:
          type: string
          minLength: 1
        url:
          type: string
          format: uri
        description:
          type: string
          minLength: 1
    Tag:
      type: string
      pattern: ^[a-zA-Z0-9-_.\/ ]*$
      minLength: 1
    Capability:
      type: object
      title: Capability
      description: Describes use-case specific capabilities, features, or configuration
      required:
      - ordId
      - type
      - title
      - version
      - releaseStatus
      - visibility
      - partOfPackage
      properties:
        ordId:
          type: string
          pattern: ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):(capability):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$
          maxLength: 255
        localId:
          type: string
          maxLength: 255
        correlationIds:
          type: array
          items:
            $ref: '#/components/schemas/CorrelationId'
        type:
          type: string
          description: Type of the capability
        customType:
          $ref: '#/components/schemas/SpecificationId'
        title:
          type: string
          minLength: 1
          maxLength: 255
        shortDescription:
          type: string
          minLength: 1
          maxLength: 255
        description:
          type: string
          minLength: 1
        partOfPackage:
          type: string
          pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(package):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$
          maxLength: 255
        partOfGroups:
          type: array
          items:
            $ref: '#/components/schemas/GroupId'
        version:
          $ref: '#/components/schemas/SemVer'
        lastUpdate:
          type: string
          format: date-time
        visibility:
          $ref: '#/components/schemas/Visibility'
        releaseStatus:
          $ref: '#/components/schemas/ReleaseStatus'
        disabled:
          type: boolean
          default: false
        minSystemVersion:
          type: string
        relatedEntityTypes:
          type: array
          items:
            type: string
            pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(entityType):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$
        definitions:
          type: array
          items:
            $ref: '#/components/schemas/CapabilityDefinition'
        links:
          type: array
          items:
            $ref: '#/components/schemas/Link'
        tags:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
        labels:
          $ref: '#/components/schemas/Labels'
        documentationLabels:
          $ref: '#/components/schemas/DocumentationLabels'
        systemInstanceAware:
          type: boolean
          default: false
    CorrelationId:
      type: string
      pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-\/]+):([a-zA-Z0-9._\-\/]+)$
      maxLength: 255
      description: Correlation ID for referencing related data
    CapabilityList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Capability'
        totalCount:
          type: integer
        limit:
          type: integer
        offset:
          type: integer
    DocumentationLabels:
      type: object
      title: Documentation Labels
      additionalProperties:
        type: array
        items:
          type: string
          minLength: 1
    Error:
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: string
          description: Error code
        message:
          type: string
          description: Human-readable error message
        details:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              message:
                type: string
        requestId:
          type: string
          description: Request ID for troubleshooting
    Labels:
      type: object
      title: Labels
      additionalProperties:
        type: array
        items:
          type: string
          minLength: 1
    AccessStrategy:
      type: object
      title: Access Strategy
      description: Defines the access strategy for accessing resource definitions
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - open
          - basic-auth
          - custom
        customType:
          $ref: '#/components/schemas/SpecificationId'
        customDescription:
          type: string
          minLength: 1
    CapabilityDefinition:
      type: object
      title: Capability Definition
      description: Link and categorization of a machine-readable capability definition
      required:
      - type
      - mediaType
      - url
      properties:
        type:
          type: string
          enum:
          - sap.mdo:mdi-capability-definition:v1
          - custom
        customType:
          $ref: '#/components/schemas/SpecificationId'
        mediaType:
          type: string
          enum:
          - application/json
          - application/xml
          - text/yaml
          - text/plain
          - application/octet-stream
        url:
          type: string
          format: uri-reference
        accessStrategies:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/AccessStrategy'
    GroupId:
      type: string
      pattern: ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+):([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+)$
      description: Valid Group ID
    SemVer:
      type: string
      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-]+)*))?$
      description: Semantic Version string following SemVer 2.0.0
  examples:
    CapabilityListExample:
      summary: List of Capabilities
      value:
        items:
        - ordId: sap.iot:capability:EdgeProcessing:v1
          title: Edge Processing Capability
          shortDescription: Process data at the edge
          type: custom
          visibility: public
          releaseStatus: active
        - ordId: sap.iot:capability:AnomalyDetection:v1
          title: ML Anomaly Detection
          shortDescription: Machine learning-based anomaly detection
          type: custom
          visibility: public
          releaseStatus: active
        totalCount: 2
        limit: 20
        offset: 0
    InternalServerErrorExample:
      summary: Internal Server Error
      value:
        code: INTERNAL_SERVER_ERROR
        message: An unexpected error occurred. Please try again later.
        requestId: req-12345-abcde
    NotFoundErrorExample:
      summary: Not Found Error
      value:
        code: NOT_FOUND
        message: The requested resource was not found
        requestId: req-12345-abcde
    CapabilityExample:
      summary: Edge Processing Capability
      value:
        ordId: sap.iot:capability:EdgeProcessing:v1
        localId: EdgeProcessing
        title: Edge Processing Capability
        shortDescription: Process data at the edge
        description: Capability to deploy and execute data processing rules on edge gateways for low-latency processing and reduced bandwidth.
        type: custom
        customType: sap.iot:edge-capability:v1
        version: 1.0.0
        releaseStatus: active
        visibility: public
        partOfPackage: sap.iot:package:DeviceManagement:v1
        definitions:
        - type: custom
          customType: sap.iot:edge-spec:v1
          mediaType: application/json
          url: /capabilities/edge-processing.json
        links:
        - title: Edge Gateway Documentation
          url: https://help.sap.com/iot/edge
    BadRequestErrorExample:
      summary: Bad Request Error
      value:
        code: BAD_REQUEST
        message: Invalid request parameters
        details:
        - field: ordId
          message: ORD ID must match the required pattern
        requestId: req-12345-abcde
  parameters:
    CapabilityTypeFilterParam:
      name: type
      in: query
      description: Filter capabilities by type
      schema:
        type: string
    LimitParam:
      name: limit
      in: query
      description: Maximum number of items to return
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
    OffsetParam:
      name: offset
      in: query
      description: Number of items to skip
      schema:
        type: integer
        minimum: 0
        default: 0
    CapabilityOrdIdParam:
      name: ordId
      in: path
      required: true
      description: ORD ID of the Capability
      schema:
        type: string
        pattern: ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):(capability):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$
      example: sap.iot:capability:EdgeProcessing:v1
  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            notFound:
              $ref: '#/components/examples/NotFoundErrorExample'
    BadRequest:
      description: Bad request - invalid input parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            badRequest:
              $ref: '#/components/examples/BadRequestErrorExample'
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            serverError:
              $ref: '#/components/examples/InternalServerErrorExample'
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 authentication
      flows:
        clientCredentials:
          tokenUrl: /oauth/token
          scopes:
            ord:read: Read access to ORD resources
            ord:write: Write access to ORD resources
            ord:admin: Administrative access to ORD resources
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT