openapi: 3.1.0
info:
  contact:
    name: Contact Us
    url: https://data.world/company/contact-us
  termsOfService: https://data.world/terms-policies
  title: data.world Public catalog relationships API
  version: '0'
  description: Manage relationships between catalog resources
servers:
- url: /v0
security:
- bearerAuth: []
tags:
- description: Manage relationships between catalog resources
  name: catalog relationships
paths:
  /metadata/relationships/{owner}/iri:
    post:
      description: If a resource A is related to resource B and C, this endpoint will return B and C. See request body for further filtering options.
      operationId: getRelationshipsByIri
      parameters:
      - description: 'User name and unique identifier of the user or organization a resource belongs to.

          For example, in the URL: https://acme.data.world/jonloyens/an-intro-to-dataworld-dataset, jonloyens is the unique identifier of the owner.

          '
        in: path
        name: owner
        required: true
        schema:
          type: string
          minLength: 1
      - description: Internationalized Resource Identifier (IRI) of the resource. You can find the IRI in the Technical Reference section under the Settings tab on the resource’s catalog page.
        in: query
        name: iri
        required: true
        schema:
          type: string
          minLength: 1
      - description: Return additional information about the resource. For example, if the resource is in a collection, the collection IRI will be returned by default. If hydration is enabled, the collection's title and description will also be returned.
        in: query
        name: hydrations
        schema:
          type: boolean
          default: false
      - description: Number of results to return
        in: query
        name: limit
        schema:
          type: integer
          format: int32
          default: 10
          maximum: 100
          minimum: 1
      - description: A token supplied by the previous response to retrieve the next page of results
        in: query
        name: next
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RelationshipGetRequestByIri'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedGenericResultsMetadataResourceDtoV2'
          description: default response
      summary: Get resources that are related to a resource identified by IRI
      tags:
      - catalog relationships
  /metadata/relationships/{owner}/iri/create:
    post:
      description: Creates a directed relationship between two catalog resources with one being the source and the other being the target.
      operationId: createRelationshipByIri
      parameters:
      - description: 'User name and unique identifier of the user or organization a resource belongs to.

          For example, in the URL: https://acme.data.world/jonloyens/an-intro-to-dataworld-dataset, jonloyens is the unique identifier of the owner.

          '
        in: path
        name: owner
        required: true
        schema:
          type: string
          minLength: 1
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RelationshipCreateOrDeleteRequestByIri'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessMessage'
          description: default response
      summary: Creates a relationship between two catalog resources identified by IRI
      tags:
      - catalog relationships
  /metadata/relationships/{owner}/iri/delete:
    post:
      description: Deletes a directed relationship between two catalog resources with one being the source and the other being the target.
      operationId: deleteRelationshipByIri
      parameters:
      - description: 'User name and unique identifier of the user or organization a resource belongs to.

          For example, in the URL: https://acme.data.world/jonloyens/an-intro-to-dataworld-dataset, jonloyens is the unique identifier of the owner.

          '
        in: path
        name: owner
        required: true
        schema:
          type: string
          minLength: 1
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RelationshipCreateOrDeleteRequestByIri'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessMessage'
          description: default response
      summary: Deletes a relationship between two catalog resources identified by IRI
      tags:
      - catalog relationships
components:
  schemas:
    ImageIcon:
      allOf:
      - $ref: '#/components/schemas/Icon'
      - type: object
        properties:
          image:
            $ref: '#/components/schemas/Image'
            oneOf:
            - $ref: '#/components/schemas/HostedImage'
            - $ref: '#/components/schemas/ProvidedImage'
          largeImage:
            $ref: '#/components/schemas/Image'
            oneOf:
            - $ref: '#/components/schemas/HostedImage'
            - $ref: '#/components/schemas/ProvidedImage'
          selectedImage:
            $ref: '#/components/schemas/Image'
            oneOf:
            - $ref: '#/components/schemas/HostedImage'
            - $ref: '#/components/schemas/ProvidedImage'
          type:
            type: string
            const: image
    PubSearchHydrations:
      type: object
      properties:
        agents:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/AgentHydrationDto'
        catalogConcepts:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/CatalogConceptHydrationDto'
        collections:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/CollectionHydrationDto'
        properties:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/PropertyHydrationDto'
        relationships:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/RelationshipHydrationDto'
        resourceHierarchy:
          type: object
          additionalProperties:
            type: object
            additionalProperties:
              type: array
              items:
                $ref: '#/components/schemas/ResourceHierarchyDto'
    ResourceDetails:
      type: object
      properties:
        typeDetails:
          $ref: '#/components/schemas/TypeDetails'
    PaginatedGenericResultsMetadataResourceDtoV2:
      type: object
      properties:
        consistent:
          type: boolean
        count:
          type: integer
          format: int32
          minimum: 0
        hydrations:
          $ref: '#/components/schemas/PubSearchHydrations'
        next:
          type: string
        records:
          type: array
          items:
            $ref: '#/components/schemas/MetadataResourceDtoV2'
    EmojiIcon:
      allOf:
      - $ref: '#/components/schemas/Icon'
      - type: object
        properties:
          type:
            type: string
            const: emoji
          value:
            type: string
    AgentHydrationDto:
      type: object
      properties:
        avatarUrl:
          type: string
        deactivated:
          type: boolean
        displayName:
          type: string
        id:
          type: string
    Image:
      type: object
      discriminator:
        mapping:
          hosted: '#/components/schemas/HostedImage'
          provided: '#/components/schemas/ProvidedImage'
        propertyName: type
      properties:
        type:
          type: string
          enum:
          - hosted
          - provided
    RelationshipGetRequestByIri:
      type: object
      properties:
        byRelationTypes:
          type: array
          description: Filter by these relation types. Relation types are identified by their IRI.
          example: https://dwec.data.world/v0/usesDataFrom
          items:
            type: string
        byResourceTypes:
          type: array
          description: Filter by these resource types. Resource types are identified by their IRI.
          items:
            type: string
    RelationshipHydrationDto:
      type: object
      properties:
        labels:
          type: array
          description: Label of the relationship presentation associated with the relationship
          items:
            type: string
    PropertyHydrationDto:
      type: object
      properties:
        label:
          type: array
          description: Label of the metadata presentation associated with the property
          items:
            type: string
    ResourceHierarchyDto:
      type: object
      properties:
        assetStatus:
          $ref: '#/components/schemas/AssetStatus'
          description: 'Resource status: Pending, Approved etc.'
        hierarchy:
          type: array
          description: Parent types of this resource's type. Returns the most specific type followed by its parent. The first item is the same as type. The last item is the root type.
          items:
            $ref: '#/components/schemas/EntryType'
        icon:
          $ref: '#/components/schemas/Icon'
          description: Resource icon details.
          oneOf:
          - $ref: '#/components/schemas/EmojiIcon'
          - $ref: '#/components/schemas/ImageIcon'
          - $ref: '#/components/schemas/SvgIcon'
        iri:
          type: string
          description: Resource IRI.
        owner:
          type: string
          description: The ID of the organization that this resource belongs to
        title:
          type: string
          description: Resource title
        type:
          type: string
          description: Resource simple type name, e.g. catalogDatabase, catalogEntry etc.
        typeLabel:
          type: string
          description: Resource type label.
    AssetStatus:
      type: object
      properties:
        assetStatusLabel:
          type: string
        dispositionLabel:
          type: string
    SvgIcon:
      allOf:
      - $ref: '#/components/schemas/Icon'
      - type: object
        properties:
          image:
            $ref: '#/components/schemas/Image'
            oneOf:
            - $ref: '#/components/schemas/HostedImage'
            - $ref: '#/components/schemas/ProvidedImage'
          largeImage:
            $ref: '#/components/schemas/Image'
            oneOf:
            - $ref: '#/components/schemas/HostedImage'
            - $ref: '#/components/schemas/ProvidedImage'
          selectedImage:
            $ref: '#/components/schemas/Image'
            oneOf:
            - $ref: '#/components/schemas/HostedImage'
            - $ref: '#/components/schemas/ProvidedImage'
          type:
            type: string
            const: svg-image
    Icon:
      type: object
      discriminator:
        mapping:
          emoji: '#/components/schemas/EmojiIcon'
          image: '#/components/schemas/ImageIcon'
          svg-image: '#/components/schemas/SvgIcon'
        propertyName: type
      properties:
        type:
          type: string
          enum:
          - emoji
          - image
          - svg-image
    StringOrArray:
      oneOf:
      - type: string
      - type: array
        items:
          type: string
    HostedImage:
      allOf:
      - $ref: '#/components/schemas/Image'
      - type: object
        properties:
          type:
            type: string
            const: hosted
          url:
            type: string
    RelationshipCreateOrDeleteRequestByIri:
      type: object
      properties:
        iri:
          type: string
          description: IRI of the relationship type
        sourceIri:
          type: string
          description: IRI of the source resource
        sourceType:
          type: string
          description: IRI of source resource's type
        targetIri:
          type: string
          description: IRI of the target resource
      required:
      - iri
      - sourceIri
      - sourceType
      - targetIri
    EntryType:
      type: object
      properties:
        icon:
          $ref: '#/components/schemas/Icon'
          oneOf:
          - $ref: '#/components/schemas/EmojiIcon'
          - $ref: '#/components/schemas/ImageIcon'
          - $ref: '#/components/schemas/SvgIcon'
        instantiable:
          type: boolean
        label:
          type: string
        pluralLabel:
          type: string
        requestable:
          type: boolean
        type:
          type: string
          description: Entry type IRI
    CollectionHydrationDto:
      type: object
      properties:
        description:
          type: string
        id:
          type: string
          description: dct:identifier of the collection
        iri:
          type: string
        owner:
          type: string
        title:
          type: string
    ProvidedImage:
      allOf:
      - $ref: '#/components/schemas/Image'
      - type: object
        properties:
          slug:
            type: string
          type:
            type: string
            const: provided
    MetadataResourceDtoV2:
      type: object
      properties:
        category:
          type: string
        collections:
          type: array
          items:
            type: string
        created:
          type: string
          format: date-time
        id:
          type: string
        iri:
          type: string
        owner:
          type: string
        properties:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/StringOrArray'
          description: All properties of the resource that are associated with a metadata presentation. Key is the IRI of the property. Value is the value of the property.
        relationshipTypes:
          type: array
          items:
            type: string
        resourceDetails:
          $ref: '#/components/schemas/ResourceDetails'
        title:
          type: string
        updated:
          type: string
          format: date-time
        url:
          type: string
          format: uri
      required:
      - created
      - updated
    CatalogConceptHydrationDto:
      type: object
      properties:
        altLabel:
          type: string
        iri:
          type: string
        owner:
          type: string
        prefLabel:
          type: string
    TypeDetails:
      type: object
      properties:
        id:
          type: string
        label:
          type: string
        subtypeOf:
          type: string
    SuccessMessage:
      type: object
      properties:
        message:
          type: string
          maxLength: 256
          minLength: 0
  securitySchemes:
    bearerAuth:
      bearerFormat: JWT
      scheme: bearer
      type: http