Application Research Data Products API

openapi: 3.2.0
info:
  title: Application Research Open Resource Discovery (ORD) Data Products 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: Data Products
  description: Data Product operations
paths:
  /data-products:
    get:
      tags:
      - Data Products
      summary: Application Research List all Data Products
      description: Retrieves a list of all Data Products across all ORD Documents
      operationId: listDataProducts
      parameters:
      - $ref: '#/components/parameters/LimitParam'
      - $ref: '#/components/parameters/OffsetParam'
      - $ref: '#/components/parameters/DataProductTypeFilterParam'
      - $ref: '#/components/parameters/DataProductCategoryFilterParam'
      responses:
        '200':
          description: Successfully retrieved list of Data Products
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataProductList'
              examples:
                dataProductList:
                  $ref: '#/components/examples/DataProductListExample'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /data-products/{ordId}:
    get:
      tags:
      - Data Products
      summary: Application Research Get a Data Product by ORD ID
      description: Retrieves a specific Data Product by its ORD ID
      operationId: getDataProduct
      parameters:
      - $ref: '#/components/parameters/DataProductOrdIdParam'
      responses:
        '200':
          description: Successfully retrieved Data Product
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataProduct'
              examples:
                dataProduct:
                  $ref: '#/components/examples/DataProductExample'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    ReleaseStatus:
      type: string
      enum:
      - beta
      - active
      - deprecated
      - sunset
    PolicyLevel:
      type: string
      description: Policy level for compliance
      oneOf:
      - type: string
        pattern: ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$
      - type: string
        enum:
        - none
        - custom
    ChangelogEntry:
      type: object
      title: Changelog Entry
      required:
      - version
      - releaseStatus
      - date
      properties:
        version:
          type: string
          minLength: 1
        releaseStatus:
          $ref: '#/components/schemas/ReleaseStatus'
        date:
          type: string
          format: date
        description:
          type: string
          minLength: 1
        url:
          type: string
          format: uri
    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
    DataProductInputPort:
      type: object
      title: Data Product Input Port
      required:
      - ordId
      properties:
        ordId:
          type: string
          pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(integrationDependency):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$
          maxLength: 255
    DataProductList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/DataProduct'
        totalCount:
          type: integer
        limit:
          type: integer
        offset:
          type: integer
    PolicyLevelId:
      type: string
      pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$
      maxLength: 255
    CustomPolicyLevel:
      type: string
      pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$
      maxLength: 255
    DataProductOutputPort:
      type: object
      title: Data Product Output Port
      required:
      - ordId
      properties:
        ordId:
          type: string
          pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(apiResource|eventResource):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$
          maxLength: 255
    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
    DocumentationLabels:
      type: object
      title: Documentation Labels
      additionalProperties:
        type: array
        items:
          type: string
          minLength: 1
    LineOfBusiness:
      type: string
      pattern: ^[a-zA-Z0-9-_.\/& ]*$
      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
    Industry:
      type: string
      pattern: ^[a-zA-Z0-9-_.\/& ]*$
      minLength: 1
    DataProduct:
      type: object
      title: Data Product
      description: A data set exposed for consumption outside the producing application
      required:
      - ordId
      - type
      - category
      - title
      - shortDescription
      - description
      - version
      - releaseStatus
      - visibility
      - partOfPackage
      - responsible
      - outputPorts
      properties:
        ordId:
          type: string
          pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(dataProduct):([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'
        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'
        partOfProducts:
          type: array
          items:
            type: string
            pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(product):([a-zA-Z0-9._\-]+):()$
            maxLength: 255
        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
        lifecycleStatus:
          type: string
          enum:
          - inactive
          - provisioning
          - active
          - deprovisioning
          - active-with-errors
          - provisioning-error
          - deprovisioning-error
        deprecationDate:
          type: string
          format: date-time
        sunsetDate:
          type: string
          format: date-time
        successors:
          type: array
          items:
            type: string
            pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(dataProduct):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$
            maxLength: 255
        changelogEntries:
          type: array
          items:
            $ref: '#/components/schemas/ChangelogEntry'
        type:
          type: string
          enum:
          - primary
          - derived
        category:
          type: string
          enum:
          - business-object
          - analytical
          - other
        entityTypes:
          type: array
          items:
            type: string
            pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(entityType):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$
            maxLength: 255
        inputPorts:
          type: array
          items:
            $ref: '#/components/schemas/DataProductInputPort'
        outputPorts:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/DataProductOutputPort'
        responsible:
          $ref: '#/components/schemas/CorrelationId'
        dataProductLinks:
          type: array
          items:
            $ref: '#/components/schemas/DataProductLink'
        links:
          type: array
          items:
            $ref: '#/components/schemas/Link'
        industry:
          type: array
          items:
            $ref: '#/components/schemas/Industry'
        lineOfBusiness:
          type: array
          items:
            $ref: '#/components/schemas/LineOfBusiness'
        countries:
          type: array
          items:
            type: string
            pattern: ^[A-Z]{2}$
        tags:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
        labels:
          $ref: '#/components/schemas/Labels'
        documentationLabels:
          $ref: '#/components/schemas/DocumentationLabels'
        policyLevel:
          $ref: '#/components/schemas/PolicyLevel'
        customPolicyLevel:
          $ref: '#/components/schemas/CustomPolicyLevel'
        policyLevels:
          type: array
          items:
            $ref: '#/components/schemas/PolicyLevelId'
        systemInstanceAware:
          type: boolean
          default: false
    Labels:
      type: object
      title: Labels
      additionalProperties:
        type: array
        items:
          type: string
          minLength: 1
    DataProductLink:
      type: object
      title: Data Product Link
      required:
      - type
      - url
      properties:
        type:
          type: string
          enum:
          - payment
          - terms-of-use
          - service-level-agreement
          - support
          - custom
        customType:
          $ref: '#/components/schemas/SpecificationId'
        url:
          type: string
          format: uri-reference
    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:
    DataProductExample:
      summary: Asset Performance Analytics Data Product
      value:
        ordId: sap.iot:dataProduct:AssetPerformance:v1
        localId: AssetPerformance
        title: Asset Performance Analytics
        shortDescription: KPIs and insights for asset performance
        description: Data product providing asset health scores, utilization metrics, failure predictions, and maintenance recommendations based on IoT sensor data.
        version: 1.0.0
        releaseStatus: active
        visibility: public
        partOfPackage: sap.iot:package:TimeSeries:v2
        type: derived
        category: analytical
        responsible: sap:ach:IOT-ANA
        inputPorts:
        - ordId: sap.iot:integrationDependency:SensorDataIngestion:v1
        outputPorts:
        - ordId: sap.iot:apiResource:TimeSeriesQuery:v2
        entityTypes:
        - sap.iot:entityType:Measurement:v1
        - sap.iot:entityType:Device:v1
        dataProductLinks:
        - type: support
          url: https://support.sap.com/iot
        lineOfBusiness:
        - Asset Management
        - Manufacturing
        industry:
        - Automotive
        - Industrial Machinery and Components
    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
    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
    DataProductListExample:
      summary: List of Data Products
      value:
        items:
        - ordId: sap.iot:dataProduct:AssetPerformance:v1
          title: Asset Performance Analytics
          shortDescription: KPIs and insights for asset performance
          type: derived
          category: analytical
          visibility: public
          releaseStatus: active
        - ordId: sap.iot:dataProduct:RawSensorData:v1
          title: Raw Sensor Data Lake
          shortDescription: Unprocessed sensor measurements
          type: primary
          category: business-object
          visibility: public
          releaseStatus: active
        totalCount: 2
        limit: 20
        offset: 0
  parameters:
    LimitParam:
      name: limit
      in: query
      description: Maximum number of items to return
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
    DataProductTypeFilterParam:
      name: type
      in: query
      description: Filter data products by type
      schema:
        type: string
        enum:
        - primary
        - derived
    DataProductOrdIdParam:
      name: ordId
      in: path
      required: true
      description: ORD ID of the Data Product
      schema:
        type: string
        pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(dataProduct):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$
      example: sap.iot:dataProduct:AssetPerformance:v1
    OffsetParam:
      name: offset
      in: query
      description: Number of items to skip
      schema:
        type: integer
        minimum: 0
        default: 0
    DataProductCategoryFilterParam:
      name: category
      in: query
      description: Filter data products by category
      schema:
        type: string
        enum:
        - business-object
        - analytical
        - other
  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