swagger: "2.0"
info:
  title: Data Sources
  version: 1.0.0
  description: |
    ```plain {% title="Client ID" %}
    prod-nam-services-fdplan.slbservice.com
    prod-eu-services-fdplan.slbservice.com
    prod-au-services-fdplan.slbservice.com
    prod-id-services-fdplan.slbservice.com
    production-services-fdplan.slbservice.com
    ```

    The data sources API is responsible for managing data sources in FDPlan.

    A **data source** is a versioned input bundle consumed by scenario evaluations. It pairs a
    user-facing `source` (a registered data type and its `store`) with one `target` data type
    understood by computations, and is discovered and reused across scenarios through `tags`
    (usually `StudyId:id`).

    Data sources are never created directly. Every data source is produced by an asynchronous
    **data source job**: the caller posts the inputs (`source`, `target`, `dataProviders`, `tags`)
    and the platform runs the transformation declared on the matching **data source type** in the
    background. A data source type is the reusable conversion contract between a domain-native input
    format and one or more evaluation-ready data types, and also declares the editors, viewers, and
    transformation/copy providers used to author and process the data.

    Key resources:
      * `data-source-types` - register and manage the conversion contracts (source/target, editors,
        viewers, providers).
      * `data-source-jobs` - create, reprocess, poll, and complete the asynchronous work that builds
        a data source. External transformers report completion via `.../{id}/state`.
      * `workflow-input-data-source-jobs` - build all workflow input data sources of a study at once
        to create virtual scenarios.
      * `data-sources` - read a given `version`, list by `tags`, and delete.
  contact:
    name: SLB Customer Support for Digital
    url: https://customersupport.digital.slb.com
  x-product-id: FDPlan-Data-Sources
host: api.delfi.slb.com
basePath: /fdplan/data-sources
schemes:
  - https
consumes:
  - application/json
produces:
  - application/json
paths:
  /v2/data-source-jobs:
    post:
      tags:
        - Data Source Job V2
      summary: Create a new data source job
      description: Create a new data source job to trigger the processing of a set of data provider sources
      operationId: postDataSourceJobV2
      produces:
        - application/json
      parameters:
        - $ref: '#/parameters/SlbPartitionId'
        - description: The data source processing job that needs to be triggered.
          name: dataSourceJob
          in: body
          required: true
          schema:
            $ref: '#/definitions/CreateDataSourceJobV2Params'
      responses:
        "202":
          description: Data source job successfully created.
          schema:
            $ref: '#/definitions/DataSourceJobV2'
        "400":
          description: Bad request.
          schema:
            $ref: '#/definitions/Error'
        "401":
          description: Unauthorized.
          schema:
            $ref: '#/definitions/Error'
        "451":
          description: Unavailable for legal reasons.
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error.
          schema:
            $ref: '#/definitions/Error'
  /v2/data-source-jobs/{dataSourceJobId}:
    get:
      tags:
        - Data Source Job V2
      summary: Get a data source job.
      description: Get a data source job.
      operationId: getDataSourceJobV2
      produces:
        - application/json
      parameters:
        - $ref: '#/parameters/SlbPartitionId'
        - required: true
          in: path
          description: The data source job to get.
          name: dataSourceJobId
          type: string
      responses:
        "200":
          description: Success.
          schema:
            $ref: '#/definitions/DataSourceJobV2'
        "400":
          description: Bad request
          schema:
            $ref: '#/definitions/Error'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/Error'
        "404":
          description: The data source job was not found.
          schema:
            $ref: '#/definitions/Error'
        "451":
          description: Unavailable for legal reasons
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error.
          schema:
            $ref: '#/definitions/Error'
    patch:
      tags:
        - Data Source Job V2
      summary: Patch a data source job.
      description: |
        Apply a JSON Patch to a data source job. This is used by an external worker during a custom
        copy flow to replace the `dataProviders` of a copy job before writing the target containers,
        so the new data source can use different sources in the context of its study. The job is
        identified by `dataSourceJobId` (for example the `data.id` from a `copy_transformation_required`
        event).
      operationId: patchDataSourceJobV2
      produces:
        - application/json
      consumes:
        - application/json
      parameters:
        - $ref: '#/parameters/SlbPartitionId'
        - required: true
          in: path
          description: The data source job to patch.
          name: dataSourceJobId
          type: string
        - description: The JSON Patch operations to apply to the data source job, for example replacing its `dataProviders`.
          name: patches
          in: body
          required: true
          schema:
            $ref: '#/definitions/PatchReq'
      responses:
        "200":
          description: Success.
          schema:
            $ref: '#/definitions/DataSourceJobV2'
        "400":
          description: Bad request
          schema:
            $ref: '#/definitions/Error'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/Error'
        "404":
          description: The data source job was not found.
          schema:
            $ref: '#/definitions/Error'
        "451":
          description: Unavailable for legal reasons
          schema:
            $ref: '#/definitions/Error'
        "503":
          description: Service Unavailable
        default:
          description: Unexpected error.
          schema:
            $ref: '#/definitions/Error'
  /v2/data-source-reprocess-jobs:
    post:
      tags:
        - Data Source Reprocess Job V2
      summary: Create a new data source reprocess job
      description: Create a new data source reprocess job to trigger the reprocessing of an existing data source.
      operationId: postDataSourceReprocessJobsV2
      produces:
        - application/json
      parameters:
        - $ref: '#/parameters/SlbPartitionId'
        - description: The data source reprocessing job that needs to be triggered.
          name: dataSourceReprocessJob
          in: body
          required: true
          schema:
            $ref: '#/definitions/ReprocessDataSourceJobV2Params'
      responses:
        "202":
          description: Data source reprocessing job successfully created.
          schema:
            $ref: '#/definitions/DataSourceReprocessJobV2'
        "400":
          description: Bad request.
          schema:
            $ref: '#/definitions/Error'
        "401":
          description: Unauthorized.
          schema:
            $ref: '#/definitions/Error'
        "451":
          description: Unavailable for legal reasons.
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error.
          schema:
            $ref: '#/definitions/Error'
  /v2/data-source-jobs/{dataSourceJobId}/state:
    post:
      tags:
        - Data Source Job V2
      summary: Set state of data source job.
      description: Set state of data source job given the data source job ID.
      operationId: postDataSourceJobStateV2
      produces:
        - application/json
      consumes:
        - application/json
      parameters:
        - $ref: '#/parameters/SlbPartitionId'
        - required: true
          in: path
          description: The data source job id to set state.
          name: dataSourceJobId
          type: string
        - description: The details of the data source job state to be set.
          name: state
          in: body
          required: true
          schema:
            $ref: '#/definitions/SetDataSourceJobState'
      responses:
        "200":
          description: The data source job state was updated.
          schema:
            $ref: '#/definitions/DataSourceJobV2'
        "400":
          description: Bad request
          schema:
            $ref: '#/definitions/Error'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/Error'
        "404":
          description: The data source job was not found.
          schema:
            $ref: '#/definitions/Error'
        "451":
          description: Unavailable for legal reasons
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error.
          schema:
            $ref: '#/definitions/Error'
  /v2/workflow-input-data-source-jobs:
    post:
      tags:
        - Data Source Job V2
      summary: Create a new workflow input data source job
      description: Create a new workflow input data source job to trigger the processing of a set of data provider sources
      operationId: postWorkflowInputDataSourceJobV2
      produces:
        - application/json
      consumes:
        - application/json
      parameters:
        - $ref: '#/parameters/SlbPartitionId'
        - description: The workflow input data source processing job that needs to be triggered.
          name: workflowInputDataSourceJob
          in: body
          required: true
          schema:
            $ref: '#/definitions/CreateWorkflowInputDataSourceJobV2Params'
      responses:
        "202":
          description: Data source job successfully created.
          schema:
            $ref: '#/definitions/DataSourceJobV2'
        "400":
          description: Bad request.
          schema:
            $ref: '#/definitions/Error'
        "401":
          description: Unauthorized.
          schema:
            $ref: '#/definitions/Error'
        "451":
          description: Unavailable for legal reasons.
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error.
          schema:
            $ref: '#/definitions/Error'
  /v2/data-sources:
    get:
      tags:
        - Data Source V2
      summary: Get list of data sources
      description: Get list of data sources.
      operationId: getDataSourcesV2
      produces:
        - application/json
      parameters:
        - $ref: '#/parameters/SlbPartitionId'
        - required: true
          in: query
          description: The tag(s) for data sources v2 to get, e.g. StudyId:ID. Multiple tags can be queried for by using a comma separated list of tags, e.g. StudyId:ID,SourceType:source-type. Only data sources whose tags match every one of the provided tags (AND logic) will be returned. StudyId (or VirtualScenarioStudyId) tag is required. A maximum of 5 tags is allowed.
          name: tags
          type: string
          pattern: ^([a-zA-Z]+:[a-zA-Z0-9\-:\.\|]+)(,([a-zA-Z]+:[a-zA-Z0-9\-:\.\|]+)){0,4}$
      responses:
        "200":
          description: Retrieved data sources v2 successfully.
          schema:
            $ref: '#/definitions/DataSourcesV2'
        "204":
          description: No data source v2 found for supplied tags.
        "400":
          description: Bad request.
          schema:
            $ref: '#/definitions/Error'
        "401":
          description: Unauthorized.
          schema:
            $ref: '#/definitions/Error'
        "451":
          description: Unavailable for legal reasons.
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error.
          schema:
            $ref: '#/definitions/Error'
  /v2/data-sources/{dataSourceId}:
    get:
      tags:
        - Data Source V2
      summary: Get a data source
      description: Get a data source given a data source ID.
      operationId: getDataSourceV2
      produces:
        - application/json
      parameters:
        - $ref: '#/parameters/SlbPartitionId'
        - required: true
          in: path
          description: The data source v2 to get.
          name: dataSourceId
          type: string
        - in: query
          description: The version of data source v2 to get.
          name: version
          type: integer
      responses:
        "200":
          description: Retrieved data source v2 successfully.
          schema:
            $ref: '#/definitions/DataSourceV2'
        "400":
          description: Bad request.
          schema:
            $ref: '#/definitions/Error'
        "401":
          description: Unauthorized.
          schema:
            $ref: '#/definitions/Error'
        "404":
          description: The data source v2 was not found.
          schema:
            $ref: '#/definitions/Error'
        "451":
          description: Unavailable for legal reasons.
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error.
          schema:
            $ref: '#/definitions/Error'
    delete:
      tags:
        - Data Source V2
      summary: Delete a data source.
      description: Delete a data source.
      operationId: deleteDataSourceV2
      produces:
        - application/json
      parameters:
        - $ref: '#/parameters/SlbPartitionId'
        - required: true
          in: path
          description: The data source to delete.
          name: dataSourceId
          type: string
      responses:
        "204":
          description: Success.
        "400":
          description: Bad request
          schema:
            $ref: '#/definitions/Error'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/Error'
        "404":
          description: The data source was not found.
          schema:
            $ref: '#/definitions/Error'
        "451":
          description: Unavailable for legal reasons
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error.
          schema:
            $ref: '#/definitions/Error'
  /v2/data-source-types:
    get:
      tags:
        - Data Source Types V2
      summary: Get list of data source types for a given target.
      description: Get list of data source types for a given target.
      operationId: getDataSourceTypes
      produces:
        - application/json
      parameters:
        - $ref: '#/parameters/SlbPartitionId'
        - in: query
          description: The data type (target) to get data source types.
          name: target
          type: string
      responses:
        "200":
          description: Success.
          schema:
            $ref: '#/definitions/DataSourceTypes'
        "204":
          description: No data source types for given target exist.
        "400":
          description: Bad request
          schema:
            $ref: '#/definitions/Error'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error.
          schema:
            $ref: '#/definitions/Error'
    post:
      tags:
        - Data Source Types V2
      summary: Create new data source type.
      description: Create new data source type.
      operationId: postDataSourceType
      produces:
        - application/json
      parameters:
        - $ref: '#/parameters/SlbPartitionId'
        - description: The data source type that needs to be created.
          name: createDataSourceType
          in: body
          required: true
          schema:
            $ref: '#/definitions/CreateDataSourceType'
      responses:
        "200":
          description: Data source type created successfully.
          schema:
            $ref: '#/definitions/DataSourceType'
        "400":
          description: Bad request
          schema:
            $ref: '#/definitions/Error'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/Error'
        "409":
          description: Conflict
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error.
          schema:
            $ref: '#/definitions/Error'
  /v2/data-source-types/{dataSourceTypeId}:
    get:
      tags:
        - Data Source Types V2
      summary: Get a data source type by ID.
      description: Get a data source type by ID.
      operationId: getDataSourceType
      produces:
        - application/json
      parameters:
        - $ref: '#/parameters/SlbPartitionId'
        - required: true
          in: path
          description: The data source type id to get.
          name: dataSourceTypeId
          type: string
      responses:
        "200":
          description: Success.
          schema:
            $ref: '#/definitions/DataSourceType'
        "400":
          description: Bad request
          schema:
            $ref: '#/definitions/Error'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/Error'
        "404":
          description: The data source type was not found.
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error.
          schema:
            $ref: '#/definitions/Error'
    patch:
      tags:
        - Data Source Types V2
      summary: Update a data source type.
      description: Update a data source type.
      operationId: patchDataSourceType
      produces:
        - application/json
      consumes:
        - application/json
      parameters:
        - $ref: '#/parameters/SlbPartitionId'
        - required: true
          in: path
          description: The data source type id to update.
          name: dataSourceTypeId
          type: string
        - description: The update to apply to the given data source type id.
          name: patch
          in: body
          required: true
          schema:
            $ref: '#/definitions/UpdateDataSourceType'
      responses:
        "200":
          description: The data source type was updated.
          schema:
            $ref: '#/definitions/DataSourceType'
        "400":
          description: Bad request
          schema:
            $ref: '#/definitions/Error'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/Error'
        "404":
          description: The data source type was not updated, because not found.
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error.
          schema:
            $ref: '#/definitions/Error'
definitions:
  Error:
    description: Generic error response.
    required:
      - data
    type: object
    properties:
      data:
        required:
          - code
        type: object
        properties:
          code:
            format: int32
            description: The HTTP status code.
            type: integer
            example: 500
            x-nullable: false
          message:
            description: The error message.
            type: string
            example: internal server error
    example:
      data:
        code: 500
        message: internal server error
  Container:
    description: A container which holds data of a given type.
    required:
      - type
      - version
      - path
    type: object
    properties:
      type:
        description: The type of the container.
        type: string
        example: price-forecast
        x-nullable: false
      version:
        description: The version of the container.
        type: integer
        example: 1
        x-nullable: false
      path:
        description: The path of the container.
        type: string
        example: 01JY6FMJMY0F6AJFV05V831SB4/containers/price-forecast/01JY6YFRF2QEVQYNGB3N31SWD5
        x-nullable: false
      description:
        description: The description of the container.
        type: string
        example: Price forecast for Robin field
        x-nullable: false
      labels:
        description: The labels of the container.
        additionalProperties:
          type: string
        type: object
        example:
          name: Base
        x-nullable: false
      store:
        description: Store is a file storage option.
        type: string
        example: fdplan
        x-nullable: false
    example:
      path: 01JY6FMJMY0F6AJFV05V831SB4/containers/price-forecast/01JY6YFRF2QEVQYNGB3N31SWD5
      type: price-forecast
      version: 1
      description: Price forecast for Robin field
      labels:
        name: Base
      store: fdplan
  LastUpdated:
    description: Details of the last update to a resource.
    required:
      - byUser
      - atDate
      - byEvent
    type: object
    properties:
      byUser:
        description: The ID of the user who made the last update.
        type: string
        example: user@slb.com
        x-nullable: false
      atDate:
        format: date-time
        description: The date time of the last update.
        type: string
        example: "2020-09-08T09:53:36.000Z"
        x-nullable: false
      byEvent:
        $ref: '#/definitions/CorrelationId'
    example:
      atDate: "2020-09-08T09:53:36.000Z"
      byEvent: 01EHPJ54HEA77K95T5KPH5JSW9
      byUser: user@slb.com
  CorrelationId:
    description: The correlation ID for the request.
    type: string
    example: 01EHPJ54HEA77K95T5KPH5JSW9
  DataSourceType:
    description: The reusable conversion contract between a domain-native input format and one or more evaluation-ready data types. Every concrete data source references one of these through its `source` and `target` pair.
    required:
      - source
      - targets
    type: object
    properties:
      id:
        description: Deterministic identifier of the data source type, derived as `source.type:source.store`.
        type: string
        example: demo:data-types:planning-assumption-reference:comm-store
        x-nullable: false
      source:
        $ref: '#/definitions/Source'
      targets:
        description: List of evaluation data types that this source can be converted into.
        type: array
        items:
          type: string
          example: price-forecast
        x-nullable: false
      editors:
        description: List of editors defining how data source type is provided.
        type: array
        items:
          $ref: '#/definitions/Editor'
        x-nullable: true
      viewers:
        description: List of viewers defining how data source type is viewed.
        type: array
        items:
          $ref: '#/definitions/Viewer'
        x-nullable: true
      transformationProvider:
        $ref: '#/definitions/TransformationProvider'
      copyProvider:
        $ref: '#/definitions/CopyProvider'
      isSystem:
        description: '`true` for built-in types shipped with the platform.'
        type: boolean
        x-nullable: false
      archived:
        description: '`true` once the type is retired and should no longer be used to create new data sources.'
        type: boolean
        x-nullable: false
    example:
      id: production-forecast-fdplan-workbook:fdplan
      editors:
        - editorURL: ""
          name: fdplan-file-selector
          type: Both
      isSystem: true
      source:
        store: fdplan
        type: production-forecast-fdplan-workbook
      targets:
        - production-forecast
      copyProvider:
        name: system
      transformationProvider:
        name: system
      viewers: []
  DataSourceTypes:
    description: List of data source types.
    required:
      - items
    type: object
    properties:
      items:
        type: array
        items:
          $ref: '#/definitions/DataSourceType'
    example:
      items:
        - id: production-forecast-fdplan-workbook:fdplan
          editors:
            - editorURL: ""
              name: fdplan-file-selector
              type: Both
          isSystem: true
          source:
            store: fdplan
            type: production-forecast-fdplan-workbook
          targets:
            - production-forecast
          copyProvider:
            name: system
          transformationProvider:
            name: system
          viewers: []
  CreateDataSourceType:
    description: Object for creating a new DataSourceType.
    required:
      - source
      - targets
    type: object
    properties:
      source:
        $ref: '#/definitions/Source'
      targets:
        description: List of Data Types.
        type: array
        items:
          type: string
          example: price-forecast
        x-nullable: false
      editors:
        description: List of editors defining how data source type is provided.
        type: array
        items:
          $ref: '#/definitions/Editor'
        x-nullable: true
      viewers:
        description: List of viewers defining how data source type is viewed.
        type: array
        items:
          $ref: '#/definitions/Viewer'
        x-nullable: true
      transformationProvider:
        $ref: '#/definitions/TransformationProvider'
      copyProvider:
        $ref: '#/definitions/CopyProvider'
    example:
      source:
        store: fdplan
        type: production-forecast-fdplan-workbook
      targets:
        - production-forecast
  UpdateDataSourceType:
    description: Object for updating an existing DataSourceType.
    type: object
    properties:
      editors:
        description: List of editors defining how data source type is provided.
        type: array
        items:
          $ref: '#/definitions/Editor'
        x-nullable: true
      viewers:
        description: List of viewers defining how data source type is viewed.
        type: array
        items:
          $ref: '#/definitions/Viewer'
        x-nullable: true
      targets:
        description: List of Data Types.
        type: array
        items:
          type: string
          example: price-forecast
        x-nullable: true
      archived:
        description: Defines if data source type is archived.
        type: boolean
        x-nullable: true
      transformationProvider:
        $ref: '#/definitions/TransformationProvider'
      copyProvider:
        $ref: '#/definitions/CopyProvider'
    example:
      targets:
        - production-forecast
  DataSourceJobV2:
    description: Data source job for creating a data source v2.
    required:
      - id
      - dataSourceId
      - dataSourceType
      - dataSourceJobType
      - dataSourceJobState
      - dataSourceJobErrors
    type: object
    properties:
      id:
        description: The ULID of the data source job, used to poll the job status and, for external transformers, to set its final state.
        type: string
        example: 01JY6YFQ5F7MYPDM3TXCGG02N2
        x-nullable: false
      dataSourceId:
        description: The id of the resulting data source. Empty string until `dataSourceJobState` reaches `Succeeded`.
        type: string
        example: 01JY6YVV4QPRH7W4TY64BXEDB6
        x-nullable: false
      dataSourceType:
        description: The resolved data source type - the `target.type`, or the full data source type id (`source.type:source.store`) when source and target share a data type.
        type: string
        example: price-forecast
        x-nullable: false
      dataSourceJobType:
        description: The data source job type. `Process` when creating a new data source, `Reprocess` when rebuilding an existing one.
        enum:
          - Process
          - Reprocess
        type: string
        example: Reprocess
        x-nullable: false
      dataSourceJobState:
        description: |
          The current lifecycle state of the data source job or reprocess job.
            * `Running`                 : the platform is staging inputs.
            * `TransformationPending`   : a `transformation_required` cloud event has been emitted to the external transformer.
            * `TransformationCompleted` : the external transformer reported success.
            * `Succeeded`               : the platform has produced the data source (terminal).
            * `Failed`                  : the job failed (terminal).
        enum:
          - Succeeded
          - Failed
          - Running
          - TransformationPending
          - TransformationCompleted
        type: string
        example: Failed
        x-nullable: false
      dataSourceJobErrors:
        description: Free-form platform-side error messages, kept distinct from the structured `transformationErrors` an external transformer may report when setting the job state.
        type: array
        items:
          type: string
        example:
          - scenario 01EFY17N9ED84BV4CHPTDAXZK1 of study 01EEST49N94JA6YJYC2KCMMPJ8 does not have any attached choices
          - scenario 1 of study 2 does not have any attached choices
    example:
      id: 01JY6YFQ5F7MYPDM3TXCGG02N2
      dataSourceId: 01JY6YVV4QPRH7W4TY64BXEDB6
      dataSourceType: price-forecast
      dataSourceJobType: Reprocess
      dataSourceJobState: Failed
      dataSourceJobErrors:
        - scenario 01EFY17N9ED84BV4CHPTDAXZK1 of study 01JY6FMJMY0F6AJFV05V831SB4 does not have any attached choices
        - scenario 1 of study 2 does not have any attached choices
  CreateDataSourceJobV2Params:
    description: Inputs for a job that creates a new data source. The `source`/`target` pair selects the matching data source type and the transformation provider that runs in the background.
    required:
      - target
    type: object
    properties:
      source:
        $ref: '#/definitions/Source'
      target:
        $ref: '#/definitions/Target'
      tags:
        description: List of tags associated with the data source, used for later discovery. `StudyId:id` is normally required to associate the data source with a study.
        type: array
        items:
          type: string
        example:
          - StudyId:01JY6FMJMY0F6AJFV05V831SB4
      description:
        description: The description for data source to be created.
        type: string
        x-nullable: false
      name:
        description: The name for data source.
        type: string
        example: Forecast Q2
      dataProviders:
        $ref: '#/definitions/DataProviders'
    example:
      source:
        type: demo:data-types:planning-assumption-reference
        store: comm-store
      target:
        type: price-forecast
      tags:
        - StudyId:01JY6FMJMY0F6AJFV05V831SB4
      description: Example of transformation
      name: Forecast Q2
      dataProviders:
        items:
          - name: Base
            description: Base price forecast deck
            sources:
              - https://corp.commercials.data-agent.com/reference/2fbcc17c7700258b/base
          - name: Stress
            description: Stress price forecast deck
            sources:
              - https://corp.commercials.data-agent.com/reference/2fbcc17c7700258b/stress
  CreateWorkflowInputDataSourceJobV2Params:
    description: Inputs for a single job that produces every workflow input data source of a study at once, in order to create virtual scenarios.
    required:
      - dataProviders
      - tags
    type: object
    properties:
      dataProviders:
        $ref: '#/definitions/WorkflowInputDataProviders'
      tags:
        description: List of tags associated with the data source. `StudyId:id` is mandatory and defines which workflow inputs are expected in `dataProviders`. Add custom tags (for example `Iteration:Iteration1`, `Case:case1`) to find virtual scenarios quickly; add `JobPriority:High` to queue the evaluations with higher priority.
        type: array
        items:
          type: string
        example:
          - StudyId:01JY6FMJMY0F6AJFV05V831SB4
      description:
        description: The description for data source to be created.
        type: string
        x-nullable: false
      name:
        description: The name for data source.
        type: string
        example: data-source-name
    example:
      dataProviders:
        items:
          - name: Base
            nodeAddress: 0:2:0
            sources:
              - 01JY6FMJMY0F6AJFV05V831SB4/files/production-forecast/01JE9MRE22QJH38W0QKF8VZ2DK/Field_Profile_Upside_Base.xlsx
            processAs:
              type: ReferenceDataSource
              value: 01JY6YVV4QPRH7W4TY64BXEDB6:v1
            description: Production forecast deck
          - name: Low
            nodeAddress: 0:2:2
            sources:
              - https://corp.commercials.data-agent.com/reference/e92276ec41f84dfb/low
            description: Low price forecast deck
          - name: Base
            nodeAddress: 0:2:2
            sources:
              - https://corp.commercials.data-agent.com/reference/e92276ec41f84dfb/base
            description: Base price forecast deck
      tags:
        - StudyId:01JY6FMJMY0F6AJFV05V831SB4
        - Iteration:Iteration1
        - Case:case1
      description: Standalone economics sensitivity
      name: VS_price_sensitivity
  DataSourceReprocessJobV2:
    description: Data source job for reprocessing a data source v2.
    required:
      - id
    type: object
    properties:
      id:
        description: The id for data source reprocess job.
        type: string
        example: 01JY6YFQ5F7MYPDM3TXCGG02N2
        x-nullable: false
    example:
      id: 01JY6YFQ5F7MYPDM3TXCGG02N2
  ReprocessDataSourceJobV2Params:
    description: Parameters for creating a data source v2 reprocessing job.
    required:
      - id
      - version
    type: object
    properties:
      id:
        description: The id for data source.
        type: string
        example: 01JY6YVV4QPRH7W4TY64BXEDB6
        x-nullable: false
      version:
        description: The version for data source.
        type: integer
        example: 1
        x-nullable: false
      dataProviders:
        $ref: '#/definitions/DataProviders'
    example:
      id: 01JY6YVV4QPRH7W4TY64BXEDB6
      version: 1
      dataProviders:
        items:
          - name: Base
            description: Base price forecast deck
            sources:
              - https://corp.commercials.data-agent.com/reference/2fbcc17c7700258b/base
          - name: Stress
            description: Stress price forecast deck
            sources:
              - https://corp.commercials.data-agent.com/reference/2fbcc17c7700258b/stress
  DataSourcesV2:
    description: List of data sources
    required:
      - items
    type: object
    properties:
      items:
        type: array
        items:
          $ref: '#/definitions/DataSourceV2'
    example:
      items:
        - id: 01JY6YVV4QPRH7W4TY64BXEDB6
          name: Forecast Q2
          description: Example of transformation
          tags:
            - StudyId:01JY6FMJMY0F6AJFV05V831SB4
          version: 1
          source:
            type: demo:data-types:planning-assumption-reference
            store: comm-store
          target:
            type: price-forecast
          details:
            dataProviders:
              items:
                - name: Base
                  description: Base price forecast deck
                  sources:
                    - https://corp.commercials.data-agent.com/reference/2fbcc17c7700258b/base
                - name: Stress
                  description: Stress price forecast deck
                  sources:
                    - https://corp.commercials.data-agent.com/reference/2fbcc17c7700258b/stress
            containers:
              - path: 01JY6FMJMY0F6AJFV05V831SB4/containers/price-forecast/01JY6YFRF2QEVQYNGB3N31SWD5
                type: price-forecast
                version: 1
                store: fdplan
                description: Price forecast for Robin field
                labels:
                  name: Base
              - path: 01JY6FMJMY0F6AJFV05V831SB4/containers/price-forecast/01JY6YFRF2TN0YKRF3NQYZJBVF
                type: price-forecast
                version: 1
                store: fdplan
                description: Price forecast for Robin field
                labels:
                  name: Stress
          lastUpdated:
            atDate: "2025-06-20T15:21:09.000Z"
            byEvent: 9510b57e-835e-9eb0-b544-407aa857226a
            byUser: user@example.com
  DataSourceV2:
    description: A versioned input bundle that feeds scenario evaluations, produced by a data source job. Reads always specify a `version`.
    required:
      - id
      - source
      - target
      - description
      - version
    type: object
    properties:
      id:
        description: The immutable id of the data source.
        type: string
        example: 01JY6YVV4QPRH7W4TY64BXEDB6
        x-nullable: false
      source:
        $ref: '#/definitions/Source'
      target:
        $ref: '#/definitions/Target'
      tags:
        description: List of tags associated with data source.
        type: array
        items:
          type: string
        example:
          - StudyId:01JY6FMJMY0F6AJFV05V831SB4
      description:
        description: The description for data source.
        type: string
        example: Example of transformation
        x-nullable: false
      type:
        description: The type for data source.
        type: string
        example: price-forecast
        x-nullable: false
      version:
        description: The revision of the data source. Rebuilding a data source after its data source type is updated produces a new version through a `Reprocess` data source job.
        type: integer
        example: 1
        x-nullable: false
      name:
        description: The name for data source.
        type: string
        example: Forecast Q2
      details:
        $ref: '#/definitions/DataSourceDetailV2'
      lastUpdated:
        $ref: '#/definitions/LastUpdated'
    example:
      id: 01JY6YVV4QPRH7W4TY64BXEDB6
      name: Forecast Q2
      description: Example of transformation
      tags:
        - StudyId:01JY6FMJMY0F6AJFV05V831SB4
      version: 1
      source:
        type: demo:data-types:planning-assumption-reference
        store: comm-store
      target:
        type: price-forecast
      details:
        dataProviders:
          items:
            - name: Base
              description: Base price forecast deck
              sources:
                - https://corp.commercials.data-agent.com/reference/2fbcc17c7700258b/base
            - name: Stress
              description: Stress price forecast deck
              sources:
                - https://corp.commercials.data-agent.com/reference/2fbcc17c7700258b/stress
        containers:
          - path: 01JY6FMJMY0F6AJFV05V831SB4/containers/price-forecast/01JY6YFRF2QEVQYNGB3N31SWD5
            type: price-forecast
            version: 1
            store: fdplan
            description: Price forecast for Robin field
            labels:
              name: Base
          - path: 01JY6FMJMY0F6AJFV05V831SB4/containers/price-forecast/01JY6YFRF2TN0YKRF3NQYZJBVF
            type: price-forecast
            version: 1
            store: fdplan
            description: Price forecast for Robin field
            labels:
              name: Stress
      lastUpdated:
        atDate: "2025-06-20T15:21:09.000Z"
        byEvent: 9510b57e-835e-9eb0-b544-407aa857226a
        byUser: user@example.com
  DataSourceDetailV2:
    description: Details of data source job.
    type: object
    properties:
      containers:
        description: List of data containers that hold the data extracted from the sources.
        type: array
        items:
          $ref: '#/definitions/Container'
        example:
          - path: 01JY6FMJMY0F6AJFV05V831SB4/containers/price-forecast/01JY6YFRF2QEVQYNGB3N31SWD5
            type: price-forecast
            version: 1
            store: fdplan
            description: Price forecast for Robin field
            labels:
              name: Base
      dataProviders:
        $ref: '#/definitions/DataProviders'
    example:
      dataProviders:
        items:
          - name: Base
            description: Base price forecast deck
            sources:
              - https://corp.commercials.data-agent.com/reference/2fbcc17c7700258b/base
          - name: Stress
            description: Stress price forecast deck
            sources:
              - https://corp.commercials.data-agent.com/reference/2fbcc17c7700258b/stress
      containers:
        - path: 01JY6FMJMY0F6AJFV05V831SB4/containers/price-forecast/01JY6YFRF2QEVQYNGB3N31SWD5
          type: price-forecast
          version: 1
          store: fdplan
          description: Price forecast for Robin field
  TransformationProvider:
    description: Transformation provider defines which provider is used to process the data.
    required:
      - name
    type: object
    properties:
      name:
        description: Provider name.
        default: system
        type: string
        x-nullable: false
  CopyProvider:
    description: Copy provider defines which provider copies the data sources of this data source type. Defaults to `system` (FDPlan copies internally); set a custom name to delegate copying to an external worker, which then handles `copy_transformation_required` events. Data source types in the `fdplan` store can only be processed by the system worker and are not allowed to have a custom copy provider.
    required:
      - name
    type: object
    properties:
      name:
        description: Provider name. Use `system` for the FDPlan copy worker, or a custom name to delegate copying to an external worker.
        default: system
        type: string
        example: comm-store-data-agent
        x-nullable: false
  Editor:
    description: Editor defines how a data source type is provided.
    required:
      - editorURL
    type: object
    properties:
      editorURL:
        description: Link to call the editor.
        type: string
        x-nullable: false
      name:
        description: Name of the editor.
        type: string
        x-nullable: true
      type:
        description: 'The type of the editor. * Default           : Editor supports legacy single item editing only * OpportunityAware  : Editor supports opportunity aware data editing only * Both              : Editor supports both legacy single item and opportunity aware data editing'
        default: Default
        enum:
          - Default
          - OpportunityAware
          - Both
        type: string
        x-nullable: false
  Viewer:
    description: Viewer defines how a data source type is viewed.
    required:
      - viewerURL
    type: object
    properties:
      viewerURL:
        description: Link to call the viewer.
        type: string
        x-nullable: false
      name:
        description: Name of the viewer.
        type: string
        x-nullable: true
      type:
        description: 'The type of the viewer. * Default           : Viewer supports legacy single item viewing only * OpportunityAware  : Viewer supports opportunity aware data viewing only * Both              : Viewer supports both legacy single item and opportunity aware data viewing'
        default: Default
        enum:
          - Default
          - OpportunityAware
          - Both
        type: string
        x-nullable: false
  Source:
    description: The user-facing input format - a registered data type and the store it lives in. Together with `target`, it selects the matching data source type.
    required:
      - type
      - store
    type: object
    properties:
      type:
        description: An existing registered Data Type that describes the domain-native input format.
        type: string
        example: demo:data-types:planning-assumption-reference
        x-nullable: false
      store:
        description: The file storage option the source data lives in (for example `comm-store`, `model`, `redms`, `fdplan`).
        type: string
        example: comm-store
        x-nullable: false
  Target:
    description: The evaluation-ready data type that computations consume, produced by the transformation.
    required:
      - type
    type: object
    properties:
      type:
        description: An existing registered evaluation Data Type.
        type: string
        example: price-forecast
        x-nullable: false
  DataProviders:
    description: List of data providers
    required:
      - items
    type: object
    properties:
      items:
        type: array
        items:
          $ref: '#/definitions/DataProvider'
    example:
      items:
        - name: Base
          description: Base price forecast deck
          sources:
            - https://corp.commercials.data-agent.com/reference/2fbcc17c7700258b/base
        - name: Stress
          description: Stress price forecast deck
          sources:
            - https://corp.commercials.data-agent.com/reference/2fbcc17c7700258b/stress
  DataProvider:
    description: Repository from which the data can be extracted including a file, folder or a datalink
    required:
      - name
      - sources
    type: object
    properties:
      name:
        description: Name of Data Provider.
        type: string
        example: Base
        x-nullable: false
      sources:
        description: List of sources that contributes to data.
        type: array
        items:
          type: string
      description:
        description: The description for data provider.
        type: string
        example: Base price forecast deck
        x-nullable: false
      metadata:
        description: The data provider metadata.
        additionalProperties:
          type: object
        type: object
        x-nullable: false
    example:
      name: Base
      description: Base price forecast deck
      sources:
        - https://corp.commercials.data-agent.com/reference/2fbcc17c7700258b/base
  WorkflowInputDataProviders:
    description: List of data providers for a workflow input data source.
    required:
      - items
    type: object
    properties:
      items:
        type: array
        items:
          $ref: '#/definitions/WorkflowInputDataProvider'
    example:
      items:
        - name: Base
          nodeAddress: 0:2:0
          sources:
            - 01JY6FMJMY0F6AJFV05V831SB4/files/production-forecast/01JE9MRE22QJH38W0QKF8VZ2DK/Field_Profile_Upside_Base.xlsx
          processAs:
            type: ReferenceDataSource
            value: 01JY6YVV4QPRH7W4TY64BXEDB6:v1
          description: Production forecast deck
        - name: Low
          nodeAddress: 0:2:2
          sources:
            - https://corp.commercials.data-agent.com/reference/e92276ec41f84dfb/low
          description: Low price forecast deck
        - name: Base
          nodeAddress: 0:2:2
          sources:
            - https://corp.commercials.data-agent.com/reference/e92276ec41f84dfb/base
          description: Base price forecast deck
  WorkflowInputDataProvider:
    description: Repository from which the data can be extracted including a file, folder or a datalink
    required:
      - name
      - nodeAddress
      - sources
    type: object
    properties:
      name:
        description: Name of data provider.
        type: string
        example: Base
        x-nullable: false
      nodeAddress:
        description: The address of the workflow input node to apply the data source binding. More than one data provider can target the same `nodeAddress` to evaluate multiple realizations within the virtual scenario.
        pattern: ^\d+:2:\d+$
        type: string
        example: 0:2:0
        x-nullable: false
      sources:
        description: List of sources that contribute to the data. When `processAs` is not specified, the sources are used as data links for the corresponding input.
        type: array
        items:
          type: string
      processAs:
        $ref: '#/definitions/WorkflowInputProcessAs'
      description:
        description: The description for data provider.
        type: string
        example: Base price forecast deck
        x-nullable: false
    example:
      name: Base
      nodeAddress: 0:2:0
      sources:
        - 01JY6FMJMY0F6AJFV05V831SB4/files/production-forecast/01JE9MRE22QJH38W0QKF8VZ2DK/Field_Profile_Upside_Base.xlsx
      processAs:
        type: ReferenceDataSource
        value: 01JY6YVV4QPRH7W4TY64BXEDB6:v1
      description: Production forecast deck
  WorkflowInputProcessAs:
    description: Information to process a workflow input data provider.
    required:
      - type
    type: object
    properties:
      type:
        description: The type to process a workflow input data provider.
        enum:
          - ReferenceDataSource
          - DataSourceType
        type: string
        x-nullable: false
      value:
        description: 'The value for the type to process a workflow input data provider. - In case of type `ReferenceDataSource` it should be an already existing data-source ID and version, format: "01JY6YVV4QPRH7W4TY64BXEDB6:v1"'
        type: string
        x-nullable: false
    example:
      type: DataSourceType
      value: production-forecast:osdu
  SetDataSourceJobState:
    description: The final state reported by an external transformer to terminate a data source job. Set `TransformationCompleted` on success, or `Failed` together with `transformationErrors`.
    type: object
    properties:
      state:
        description: The terminal state to set for the data source job.
        enum:
          - Failed
          - TransformationCompleted
        type: string
        x-nullable: false
      transformationErrors:
        $ref: '#/definitions/TransformationErrors'
    example:
      state: Failed
      transformationErrors:
        items:
          - message: scenario 01EFY17N9ED84BV4CHPTDAXZK1 of study 01JY6FMJMY0F6AJFV05V831SB4 does not have any attached choices
          - message: scenario 1 of study 2 does not have any attached choices
  TransformationErrors:
    description: Structured errors reported by an external transformer when terminating a data source job with state `Failed`.
    required:
      - items
    type: object
    properties:
      items:
        type: array
        items:
          $ref: '#/definitions/TransformationError'
  TransformationError:
    description: A single transformation error, optionally scoped to the data providers it affects.
    required:
      - message
    type: object
    properties:
      dataProviderNames:
        description: Names of the data providers this error relates to.
        type: array
        items:
          type: string
      message:
        description: The error message.
        type: string
  PatchReq:
    description: An ordered list of JSON Patch operations to apply to a data source job.
    minItems: 1
    type: array
    items:
      $ref: '#/definitions/PatchItem'
    example:
      - op: replace
        path: dataProviders
        value:
          items:
            - name: Base
              sources:
                - https://corp.commercials.data-agent.com/reference/01K0F086K8HD3SBMHQ1N0W6J2P/Base
  PatchItem:
    description: A JSONPatch document as defined by RFC 6902.
    required:
      - op
      - path
    properties:
      op:
        description: The operation to be performed.
        enum:
          - add
          - remove
          - replace
        type: string
        x-nullable: false
      path:
        description: A JSON-Pointer to the field to update, for example `dataProviders`.
        type: string
        example: dataProviders
        x-nullable: false
      value:
        description: The value to be used within the operation, for example a `dataProviders` object with its `items`.
        type: object
parameters:
  SlbPartitionId:
    required: true
    in: header
    description: Data partition id.
    name: slb-partition-id
    type: string
security:
  - bearer: []
    appkey: []
securityDefinitions:
  bearer:
    type: apiKey
    name: Authorization
    in: header
  appkey:
    type: apiKey
    name: appkey
    in: header
tags:
  - name: Data Source Job V2
    description: Managing data source jobs.
  - name: Data Source Reprocess Job V2
    description: Managing data source reprocessing jobs.
  - name: Data Source V2
    description: Managing data sources.
  - name: Data Source Types V2
    description: Managing data source types.