http_binding_openapi.yaml

openapi: "3.0.0"
info:
  description: "IDS spec"
  version: "0.8"
  title: "IDS http binding"
  
  license:
    name: "Apache 2.0"
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"


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
            dspace:processId:
              type: string
              description: "This is an EDC workaround"

    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/CatalogOffer"
        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

    # rather not used any more. Use strings instead
    OdrlOperand:
      type: object
      properties:
        value:
          type: string
    OdrlOperator:
      type: object
      properties:
        "@id":
          type: string

    OdrlConstraint:
      type: object
      properties:
        "@type":
          type: string
          #default: "Constraint"
        odrl:leftOperand:
          type: string
        odrl:operator:
          oneOf:
            - type: string
            - $ref: "#/components/schemas/OdrlOperator"
        odrl:rightOperand:
          type: string

    OdrlLogicalConstraint:
      description: "TODO: also add andSequence, or, xone as described here: https://www.w3.org/TR/odrl-vocab/#term-operand"
      type: object
      properties:
        "@id":
          type: string
        "@type":
          type: string
          default: "LogicalConstraint"
        "odrl:and":
          oneOf:
            # this is the EDC issue of serializing lists with single item into non-lists
            - $ref: "#/components/schemas/OdrlConstraint"
            - type: array
              items:
                $ref: "#/components/schemas/OdrlConstraint"
        "odrl:or":
          type: array
          items:
            $ref: "#/components/schemas/OdrlConstraint"
        # TODO: https://www.w3.org/TR/odrl-vocab/#term-LogicalConstraint
        # andSequence, xone



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

    OdrlRule:
      description: "The Rule class is the parent of the Permission, Prohibition, and Duty classes. https://www.w3.org/TR/odrl-model/#rule"
      type: object
      required:
        - odrl:action
      properties:
        odrl:action:
          oneOf:
            - type: string
            - $ref: "#/components/schemas/Action"
        # "A Rule MAY have none or one relation sub-property values of type Asset."
        # "Explicit sub-properties of the abstract relation, relation and failure
        # properties must be used, the choice depending on the subclass of Rule in question."
        # -> needs to go into subclasses, e.g. OdrlPermission
        odrl:constraint:
          oneOf:
            # LogicalConstraint
            - $ref: "#/components/schemas/OdrlLogicalConstraint"
            # to easier parse the object we don't allow the theoretical possible list of LCs
            # - type: array
            #   items:
            #     $ref: "#/components/schemas/OdrlLogicalConstraint"
            # Constraint
            - $ref: "#/components/schemas/OdrlConstraint"
            - type: array
              items:
                $ref: "#/components/schemas/OdrlConstraint"
        # duty must be defined with their property names in the subclasses, e.g. Permission, Prohibition or Duty
        # Since we don't have those yet, all are Rules
        #odrl:duty:
        #  type: array
        #  items:
        #    type: string # TODO: what is this exactly?

    OdrlPermission:
      description: "https://www.w3.org/TR/odrl-model/#permission"
      type: object
      allOf:
        - $ref: "#/components/schemas/OdrlRule"
        - type: object
          properties:
            odrl:target:
              type: string
              description: "ODRL requires this. DSP did remove it (MUST NOT) and is thinking about to get it back in again. EDC also requires it."
      # TODO: may properties: assigner/assignee, duty

    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:profile:
          type: string
        odrl:permission:
          oneOf:
            - $ref: "#/components/schemas/OdrlPermission"
            - type: array
              items:
                $ref: "#/components/schemas/OdrlPermission"
        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"
    CatalogOffer:
      description: "In DSP, the Offer in the catalog does explicitly NOT have a target, since it is given from the enclosing context."
      allOf:
        - $ref: "#/components/schemas/OdrlPolicy"
        - type: object
          properties:
            "@type":
              type: string
              default: "odrl:Offer"
    OdrlOffer:
      description: "Only addition compared to the Policy: the target field - which should not be there according to DSP model"
      allOf:
        - $ref: "#/components/schemas/OdrlPolicy"
        - type: object
          properties:
            "@type":
              type: string
              default: "odrl:Offer"
            odrl:target:
              type: string
              description: "This is used in EDC, but according to DSP model, this should be removed"
              deprecated: true
    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