openapi: 3.2.0
info:
  title: Catalog Service V2 Datasets API
  description: "Catalog is the system of record for data location and lineage within Adobe Experience Platform. Catalog Service does not contain the actual files or directories that contain the data. Instead, it holds the metadata and description of those files and directories.\n\nCatalog acts as a metadata store or \"catalog\" where you can find information about your data within Experience Platform.\n\nUse Catalog to answer the following questions: Where is my data located? At what stage of processing is this data? What systems or processes have acted on my data? What errors occurred during processing? If successful, how much data was processed?\n\n- **Related documentation**:\n    - [Catalog Service documentation](http://www.adobe.com/go/data-catalog-service-overview-en)\n\n- **Visualize API calls with Postman (a free, third-party software)**:\n    - [Catalog Service API Postman collection on GitHub](https://github.com/adobe/experience-platform-postman-samples/blob/master/apis/experience-platform/Catalog%20Service%20API.postman_collection.json)\n    - [Video guide for creating the Postman environment](https://video.tv.adobe.com/v/28832)\n    - [Steps for importing environments and collections in Postman](https://learning.postman.com/docs/getting-started/importing-and-exporting-data/)\n\n- **API paths**:\n    - PLATFORM Gateway URL: https://<span>platform.adobe.io/\n    - Base path for this API: /data/foundation/catalog\n    - Example of a complete path: https://<span>platform.adobe.io/data/foundation/catalog/batches\n\n- **Required headers**:\n    - All calls require the headers `Authorization`, `x-gw-ims-org-id`, and `x-api-key`. For more information on how to obtain these values, see the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).\n    - All resources in Experience Platform are isolated to specific virtual sandboxes. All requests to Platform APIs require the header `x-sandbox-name` whose value is the all-lowercase name of the sandbox the operation will take place in (for example, \"prod\"). See the [sandboxes overview](https://adobe.com/go/sandbox-overview-en) for more information.\n    - All requests with a payload in the request body (such as POST, PUT, and PATCH calls) must include the header `Content-Type` with a value of `application/json`.\n\n- **API error handling**:\n    - Refer to the Experience Platform API troubleshooting guide for [FAQs](https://experienceleague.adobe.com/docs/experience-platform/landing/troubleshooting.html#faq), [API status codes](https://experienceleague.adobe.com/docs/experience-platform/landing/troubleshooting.html#api-status-codes), and [request header errors](https://experienceleague.adobe.com/docs/experience-platform/landing/troubleshooting.html#request-header-errors).\n- **Sorting and filtering responses**:\n    - When performing listing (GET) requests in the Catalog Service API, you can use query parameters to [sort and filter responses](https://experienceleague.adobe.com/docs/experience-platform/catalog/api/filter-data.html)."
  version: '1.0'
servers:
- url: //{environment}.adobe.io/data/foundation/catalog
  variables:
    environment:
      default: platform
      enum:
      - platform
      - platform-stage
tags:
- name: V2 Datasets
  description: Provides advanced dataset updates with dynamic merging and automatic creation of nested objects, simplifying modifications and reducing errors.
paths:
  /v2/dataSets/{DATASET_ID}:
    patch:
      tags:
      - V2 Datasets
      summary: Update dataset attributes using PATCH v2
      description: "Updates specific dataset attributes, including deeply nested fields, using PATCH v2. \nMissing intermediate objects are automatically created during the update process.\n"
      operationId: patchDataSetV2
      parameters:
      - $ref: '#/components/parameters/dataset_id'
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/x-api-key'
      - $ref: '#/components/parameters/x-gw-ims-org-id'
      - $ref: '#/components/parameters/x-sandbox-name'
      - $ref: '#/components/parameters/content-type'
      - $ref: '#/components/parameters/if-match'
      - $ref: '#/components/parameters/if-none-match'
      requestBody:
        description: A JSON object containing the dataset attributes to update.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/datasetPatchRequestV2'
              additionalProperties: true
      responses:
        200:
          x-summary: Dataset updated successfully.
          description: A successful response returns an array containing the ID of the updated dataset, which matches the ID sent in the PATCH request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/datasetUpdateResponse'
        400:
          description: A bad request.
        403:
          description: Access is forbidden.
        404:
          description: Dataset not found.
        500:
          description: An internal server error has ocurred.
components:
  parameters:
    if-match:
      name: if-match
      in: header
      description: Set to verify the valid versions of document to be modified by matching the updated date.
      schema:
        type: string
    dataset_id:
      name: DATASET_ID
      in: path
      description: The ID of the dataset.
      required: true
      schema:
        type: string
    authorization:
      name: Authorization
      in: header
      description: The access token which can be copied from your Experience Platform integration, prefixed with "Bearer". For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
      required: true
      schema:
        type: string
    if-none-match:
      name: if-none-match
      in: header
      description: Set to verify the invalid versions of document to be modified by matching the updated date.
      schema:
        type: string
    content-type:
      name: content-type
      in: header
      description: Specifies the media type of the request body. Required for requests with a payload, such as POST, PUT, and PATCH. When sending a JSON payload, this must be set to `application/json`.
      required: true
      schema:
        type: string
        enum:
        - application/json
    x-api-key:
      name: x-api-key
      in: header
      description: The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
      required: true
      schema:
        type: string
    x-gw-ims-org-id:
      name: x-gw-ims-org-id
      in: header
      description: The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
      required: true
      schema:
        type: string
    x-sandbox-name:
      name: x-sandbox-name
      in: header
      description: The name of the sandbox in which the operation will take place. See the [sandboxes overview documentation](https://adobe.com/go/sandbox-overview-en) for more information.
      required: true
      schema:
        type: string
  schemas:
    datasetUpdateResponse:
      type: array
      items:
        type: string
        example: '@/dataSets/67b3077efa10d92ab7a71858'
    datasetPatchRequestV2:
      type: object
      properties:
        description:
          type: string
          description: The updated description of the dataset.
          example: Updated dataset for Q2 sales analysis
        tags:
          type: object
          description: Tags associated with the dataset.
          properties:
            adobe/pqs/table:
              type: array
              items:
                type: string
              description: An identifier for the dataset table.
              example: q2_sales_data
            adobe/siphon/table/format:
              type: array
              items:
                type: string
              description: The format of the dataset table.
              example: parquet
        extensions:
          type: object
          description: Dataset extensions containing additional metadata.
          properties:
            adobe_lakeHouse:
              type: object
              description: Data lake related configurations.
              properties:
                rowExpiration:
                  type: object
                  description: The configuration for automatic row expiration.
                  properties:
                    ttlValue:
                      type: string
                      description: The TTL (time-to-live) for row expiration, expressed in ISO 8601 duration format.
                      example: P3Y
                  required:
                  - ttlValue
              required:
              - rowExpiration
          required:
          - adobe_lakeHouse
        classification:
          type: object
          description: Categorization and management information for the dataset.
          properties:
            dataBehavior:
              type: string
              description: Indicates the data processing type.
              example: time-series
            managedBy:
              type: string
              description: Specifies the entity responsible for managing the dataset.
              enum:
              - CUSTOMER
              - SYSTEM
              example: CUSTOMER
          required:
          - dataBehavior
          - managedBy
      additionalProperties: true