public-endpoints.yaml

openapi: 3.0.1
info:
  title: sovity EDC CE Public Endpoints
  version: 5.0.0
  description: |
    These are the required publicly exposed endpoints on our sovity EDC Community Edition Connectors.
    
    As the Eclipse EDC Connectors uses Data Space Protocol (DSP) for connector-to-connector communication, this includes all protocol endpoints.  
    
    Please note that the DSP HTTP endpoints use JSON-LD documents, which must be semantically interpreted and thus cannot be represented correctly via OpenAPI.

    Links:
      - [DSP Version 0.8 Full Specification](https://github.com/International-Data-Spaces-Association/ids-specification/tree/v0.8)
      - [DSP Version 0.8 HTTP OpenAPI](https://github.com/boschresearch/py-cx-ids/blob/ed62e4ad92e4715551e081a9d27f58ea6919faaa/pycxids/core/http_binding/http_binding_openapi.yaml) by Matthias Binzer <matthias.binzer@de.bosch.com>
  license:
    name: "Apache 2.0"
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"
servers:
  - url: https://[MY_EDC_FQDN]/api/dsp
tags:
  - name: "Catalog"
    description: "Catalog endpoints"

  - name: "Negotiation"
    description: "Negotiation Process - Provider side"

  - name: "Negotiation Callbacks"
    description: "Negotiation Process Callbacks - Consumer side"

  - name: "Transfer"
    description: "Transfer Process"

paths:
  /catalog/request:
    post:
      tags:
        - "Catalog"
      requestBody:
        required: True
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CatalogRequestMessage"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DcatCatalog"
          description: "Result"
  /catalog/datasets/{id}:
    get:
      tags:
        - "Catalog"
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: "Result"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DcatDataset"

  /negotiations/{id}:
    get:
      tags:
        - "Negotiation"
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: "Result"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContractNegotiation"

  /negotiations/request:
    post:
      tags:
        - "Negotiation"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ContractRequestMessage"
      responses:
        "201":
          description: "The provider connector must return an HTTP 201 (Created) response with the location header set to the location of the contract negotiation and a body containing the ContractNegotiation message"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContractNegotiation"
  /negotiations/{id}/request:
    post:
      tags:
        - "Negotiation"
      description: "The consumer must include the processId. The consumer must include either the offer or offerId property."
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ContractRequestMessage"
      responses:
        "200":
          description: "If the message is successfully processed, the provider connector must return and HTTP 200 (OK) response. The response body is not specified and clients are not required to process it."
  /negotiations/{id}/events:
    post:
      tags:
        - "Negotiation"
      description: "The consumer must include the processId. The consumer must include either the offer or offerId property."
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ContractNegotiationEventMessage"
      responses:
        "200":
          description: "Result"
  /negotiations/{id}/agreement/verification:
    post:
      tags:
        - "Negotiation"
      description: "TODO"
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ContractAgreementVerificationMessage"
      responses:
        "200":
          description: "Result"
  /negotiations/{id}/termination:
    post:
      tags:
        - "Negotiation"
      description: "TODO"
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ContractNegotiationTerminationMessage"
      responses:
        "200":
          description: "Result"

  /negotiations/{id}/offer:
    post:
      tags:
        - "Negotiation Callbacks"
      description: "Callback on the Consumer side"
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ContractOfferMessage"
      responses:
        "200":
          description: "Result"
  /negotiations/{id}/agreement:
    post:
      tags:
        - "Negotiation Callbacks"
      description: "Callback on the Consumer side"
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ContractAgreementMessage"
      responses:
        "200":
          description: "Result"

  /transfers/request:
    post:
      tags:
        - "Transfer"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TransferRequestMessage"
      responses:
        "201":
          description: "The provider connector must return an HTTP 201 (Created) response with the location header set to the location of the transfer process and a body containing the TransferProcess message"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TransferProcess"


components:
  schemas:

    DspaceFilter:
      type: object

    CatalogRequestMessage:
      allOf:
        - $ref: "#/components/schemas/JsonLd"
        - type: object
          description: "TODO: not finished yet"
          properties:
            "@type":
              type: string
              default: "dspace:CatalogRequestMessage"
            filter:
              $ref: "#/components/schemas/DspaceFilter"

    ContractRequestMessage:
      allOf:
        - $ref: "#/components/schemas/JsonLd"
        - type: object
          description: "TODO: not finished yet"
          properties:
            "@type":
              type: string
              default: "dspace:ContractRequestMessage"
            dspace:dataset:
              type: string
              description: "@id of the dataset"
            dspace:dataSet:
              type: string
              description: "Only there for compatibility reasons. Seems to be a type in the spec"
            dspace:processId:
              type: string
              description: "TODO: Deprecated? To be removed?"
            dspace:offer:
              $ref: "#/components/schemas/OdrlOffer"
            dspace:callbackAddress:
              type: string

    ContractNegotiationEventMessage:
      allOf:
        - $ref: "#/components/schemas/JsonLd"
        - type: object
          description: "TODO: not finished yet"
          properties:
            "@type":
              type: string
              default: "dspace:ContractNegotiationEventMessage"
            "dspace:processId":
              type: string
            "dspace:eventType":
              type: string
              enum:
                - "https://w3id.org/dspace/v0.8/FINALIZED"
                - "https://w3id.org/dspace/v0.8/ACCEPTED"
                - "https://w3id.org/dspace/v0.8/TERMINATED"

    ContractAgreementVerificationMessage:
      allOf:
        - $ref: "#/components/schemas/JsonLd"
        - type: object
          description: "TODO: not finished yet"
          properties:
            "@type":
              type: string
              default: "dspace:ContractAgreementVerificationMessage"
            "dspace:processId":
              type: string

    ContractNegotiationTerminationMessage:
      allOf:
        - $ref: "#/components/schemas/JsonLd"
        - type: object
          description: "TODO: not finished yet"
          properties:
            "@type":
              type: string
              default: "dspace:ContractNegotiationTerminationMessage"
            "dspace:processId":
              type: string
            "dspace:code":
              type: string
              description: "TODO: not documented?"
            "dspace:reason":
              description: "TODO: can be a link / @id too"
              type: array
              items:
                $ref: "#/components/schemas/LanguageValue"

    ContractOfferMessage:
      allOf:
        - $ref: "#/components/schemas/JsonLd"
        - type: object
          description: "Used for Tranistion Requested -> Offered from Provider -> Consumer Callback endpoint"
          properties:
            "@type":
              type: string
              default: "dspace:ContractOfferMessage"
            dspace:processId:
              type: string
            dspace:offer:
              $ref: "#/components/schemas/OdrlOffer"
            dspace:callbackAddress:
              type: string

    ContractAgreementMessage:
      allOf:
        - $ref: "#/components/schemas/JsonLd"
        - type: object
          description: "Used for Tranistion Requested -> Agreed from Provider -> Consumer Callback endpoint"
          properties:
            "@type":
              type: string
              default: "dspace:ContractAgreementMessage"
            dspace:processId:
              type: string
            dspace:agreement:
              $ref: "#/components/schemas/OdrlAgreement"
            dspace:callbackAddress:
              type: string


    ContractNegotiation:
      allOf:
        - $ref: "#/components/schemas/JsonLd"
        - type: object
          properties:
            "@type":
              type: string
              default: "dspace:ContractNegotiation"
            "dspace:processId":
              type: string
            "dspace:state":
              $ref: "#/components/schemas/TransferState"

    TransferRequestMessage:
      allOf:
        - $ref: "#/components/schemas/JsonLd"
        - type: object
          description: "Used for Transfer Tranistion Start -> Requested from Consumer -> Provider"
          properties:
            "@type":
              type: string
              default: "dspace:TransferRequestMessage"
            dspace:agreementId:
              type: string
              description: "The agreementId property refers to an existing contract agreement between the consumer and provider."
            dct:format:
              type: string
              description: "The dct:format property is a format specified by a Distribution for the Asset associated with the agreement. This is generally obtained from the provider Catalog."
            dspace:dataAddress:
              type: string
              description: "The dataAddress property must only be provided if the dct:format requires a push transfer."
            dspace:callbackAddress:
              type: string

    TransferStartMessage:
      allOf:
        - $ref: "#/components/schemas/JsonLd"
        - type: object
          description: "Used for Transfer Tranistion Requested -> Started from Provider -> Consumer"
          properties:
            "@type":
              type: string
              default: "dspace:TransferStartMessage"
            dspace:processId:
              type: string
            dspace:dataAddress:
              oneOf:
                - type: object
                  additionalProperties:
                    type: string
                - type: string

    TransferProcess:
      allOf:
        - $ref: "#/components/schemas/JsonLd"
        - type: object
          properties:
            "@type":
              type: string
              default: "dspace:TransferProcess"
            dspace:processId:
              type: string
            dspace:state:
              $ref: "#/components/schemas/TransferState"

    NegotiationState:
      type: string
      enum:
        - REQUESTED
        - OFFERED
        - ACCEPTED
        - AGREED
        - VERIFIED
        - FINALIZED
        - TERMINATED

    TransferState:
      type: string
      enum:
        - REQUESTED
        - STARTED
        - TERMINATED
        - COMPLETED
        - SUSPENDED


    LanguageValue:
      type: object
      properties:
        "@value":
          type: string
        "@language":
          type: string

    JsonLd:
      type: object
      properties:
        "@context":
          type: object
          items:
            type: string
          default: {
            "dct": "https://purl.org/dc/terms/",
            "tx": "https://w3id.org/tractusx/v0.0.1/ns/",
            "edc": "https://w3id.org/edc/v0.0.1/ns/",
            "dcat": "https://www.w3.org/ns/dcat/",
            "odrl": "http://www.w3.org/ns/odrl/2/",
            "dspace": "https://w3id.org/dspace/v0.8/"
          }
        "@id":
          type: string


    DcatDataset:
      type: object
      properties:
        "@id":
          type: string
        "@type":
          type: string
          default: "dcat:Dataset"
        dct:title:
          type: string
        dct:description:
          type: string
        dct:keyword:
          type: array
          items:
            type: string
        odrl:hasPolicy:
          type: array
          items:
            $ref: "#/components/schemas/OdrlPolicy"
        dcat:distribution:
          $ref: "#/components/schemas/DcatDistribution"

    DcatCatalog:
      allOf:
        - $ref: "#/components/schemas/JsonLd"
        - type: object
          properties:
            "@type":
              type: string
              default: "dcat:Catalog"
            "dct:title":
              type: string
            "dct:publisher":
              type: string
            "dcat:keyword":
              type: array
              items:
                type: string
            dcat:service:
              $ref: "#/components/schemas/DcatService"
            dcat:dataset:
              type: array
              items:
                $ref: "#/components/schemas/DcatDataset"
              default: []

    DcatDistribution:
      type: object
      properties:
        "@type":
          type: string
        dct:format:
          type: string
        dcat:accessService:
          type: string

    DcatService:
      type: object
      properties:
        "@id":
          type: string
        "@type":
          type: string
        dct:terms:
          type: string
        dct:endpointUrl:
          type: string


    OdrlOperand:
      type: object
      properties:
        value:
          type: string
    OdrlConstraint:
      type: object
      properties:
        odrl:leftOperand:
          $ref: "#/components/schemas/OdrlOperand"
        odrl:rightOperand:
          $ref: "#/components/schemas/OdrlOperand"
        odrl:operator:
          type: string

    Action:
      type: object
      properties:
        odrl:type:
          type: string

    OdrlRule:
      type: object
      properties:
        odrl:action:
          oneOf:
            - type: string
            - $ref: "#/components/schemas/Action"
        odrl:constraint:
          $ref: "#/components/schemas/OdrlConstraint"
        odrl:duty:
          type: array
          items:
            type: string # TODO: what is this exactly?
    OdrlPolicy:
      description: "In IDS http binding explicitly does NOT have a target, because this is derived from the enclosing context!"
      type: object
      properties:
        "@id":
          type: string
        "@type":
          type: string
          default: "odrl:Policy"
        odrl:permission:
          oneOf:
            - $ref: "#/components/schemas/OdrlRule"
            - type: array
              items:
                $ref: "#/components/schemas/OdrlRule"
        odrl:prohibition:
          oneOf:
            - $ref: "#/components/schemas/OdrlRule"
            - type: array
              items:
                $ref: "#/components/schemas/OdrlRule"
        odrl:obligation:
          oneOf:
            - $ref: "#/components/schemas/OdrlRule"
            - type: array
              items:
                $ref: "#/components/schemas/OdrlRule"
    OdrlOffer:
      description: "Only addition compared to the Policy: the target field"
      allOf:
        - $ref: "#/components/schemas/OdrlPolicy"
        - type: object
          properties:
            "@type":
              type: string
              default: "odrl:Offer"
            odrl:target:
              type: string
    OdrlAgreement:
      description: "Agreement"
      allOf:
        - $ref: "#/components/schemas/OdrlPolicy"
        - type: object
          properties:
            "@type":
              type: string
              default: "odrl:Agreement"
            odrl:target:
              type: string
            dspace:timestamp:
              oneOf:
                - $ref: "#/components/schemas/DspaceTimestamp"
                - type: string
            dspace:consumerId:
              type: string
            dspace:providerId:
              type: string
    DspaceTimestamp:
      description: "xsd:dateTime"
      properties:
        "@type":
          type: string
          default: "xsd:dateTime"
        "@value":
          type: string