info:
  description: |
    API for managing data products

    This API requires having the data products feature enabled
  title: Data Products API
  version: 0.2.3
openapi: 3.0.0

  #####
  # TAGS
  #####

tags:
  - description: These endpoints can be used to manage data products
    name: Data Products
  - description: These endpoints can be used to manage data product versions
    name: Data Product Versions
  - description: These endpoints can be used to manage data marketplaces
    name: Data Marketplaces
  - description: These endpoints can be used to publish data products in marketplaces
    name: Data Products Publishing
  - description: These endpoints can be used to search data products
    name: Data Products Search
  - description: These endpoints can be used to manage permissions for app, marketplaces, and data products
    name: Permissions

  #####
  # PATHS
  #####

paths:
  /integration/data-products/v1/data-product/:
    get:
      description: Retrieves a list of data products
      operationId: list_data_products
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
      responses:
        200:
          description: Data products found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataProducts'
              examples:
                DataProducts:
                  $ref: '#/components/examples/DataProducts'
        403:
          $ref: '#/components/responses/403_Error'
      summary: Get all data products
      tags:
        - Data Products
    post:
      description: Creates a new data product
      operationId: create_data_product
      requestBody:
        content:
          application/x-yaml:
            schema:
              $ref: '#/components/schemas/SpecJson'
            examples:
              Spec:
                $ref: '#/components/examples/ProductSpecYaml'
          application/json:
            schema:
              $ref: '#/components/schemas/SpecJson'
            examples:
              Spec:
                $ref: '#/components/examples/ProductSpecJson'
      responses:
        201:
          description: Data product created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataProduct'
              examples:
                DataProduct:
                  $ref: '#/components/examples/DataProduct'
        400:
          $ref: '#/components/responses/400_Error'
        403:
          $ref: '#/components/responses/403_Error'
      summary: Create a data product
      tags:
        - Data Products
    put:
      description: Updates a specific data product
      operationId: update_data_product
      requestBody:
        content:
          application/x-yaml:
            schema:
              $ref: '#/components/schemas/SpecJson'
            examples:
              Spec:
                $ref: '#/components/examples/ProductSpecYaml'
          application/json:
            schema:
              $ref: '#/components/schemas/SpecJson'
            examples:
              Spec:
                $ref: '#/components/examples/ProductSpecJson'
      responses:
        200:
          description: Data product updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataProduct'
              examples:
                DataProduct:
                  $ref: '#/components/examples/DataProduct'
        400:
          $ref: '#/components/responses/400_Error'
        403:
          $ref: '#/components/responses/403_Error'
        404:
          $ref: '#/components/responses/404_Error'
      summary: Update a data product
      tags:
        - Data Products
  /integration/data-products/v1/data-product/{product_id}/:
    get:
      description: Retrieves details of a specific data product
      operationId: get_data_product
      parameters:
        - $ref: '#/components/parameters/product_id'
      responses:
        200:
          description: Data product found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataProduct'
              examples:
                DataProduct:
                  $ref: '#/components/examples/DataProduct'
        403:
          $ref: '#/components/responses/403_Error'
        404:
          $ref: '#/components/responses/404_Error'
      summary: Get a specific data product
      tags:
        - Data Products
    delete:
      description: Deletes a specific data product
      operationId: delete_data_product
      parameters:
        - $ref: '#/components/parameters/product_id'
      responses:
        204:
          description: Data product deleted successfully
        403:
          $ref: '#/components/responses/403_Error'
        404:
          $ref: '#/components/responses/404_Error'
      summary: Delete a data product
      tags:
        - Data Products
  /integration/data-products/v1/data-product/{product_id}/version/{version_id}/:
    get:
      description: Retrieves a data product varsion
      operationId: get_data_product_version
      parameters:
        - $ref: '#/components/parameters/product_id'
        - $ref: '#/components/parameters/version_id'
      responses:
        200:
          description: Data product version found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataProduct'
              examples:
                DataProducts:
                  $ref: '#/components/examples/DataProduct'
        403:
          $ref: '#/components/responses/403_Error'
      summary: Get data product version
      tags:
        - Data Product Versions
    put:
      description: Updates status of particular data product version
      operationId: update_data_product_version
      parameters:
        - $ref: '#/components/parameters/product_id'
        - $ref: '#/components/parameters/version_id'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                  description: Status of the data product (draft, ready)
                  example: draft
      responses:
        201:
          description: Data product version updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataProduct'
              examples:
                DataProduct:
                  $ref: '#/components/examples/DataProduct'
        400:
          $ref: '#/components/responses/400_Error'
        403:
          $ref: '#/components/responses/403_Error'
      summary: Update a data product version status
      tags:
        - Data Product Versions
    delete:
      description: Deletes a specific data product version
      operationId: delete_data_product_version
      parameters:
        - $ref: '#/components/parameters/product_id'
        - $ref: '#/components/parameters/version_id'
      responses:
        204:
          description: Data product version deleted successfully
        403:
          $ref: '#/components/responses/403_Error'
        404:
          $ref: '#/components/responses/404_Error'
      summary: Delete a data product version
      tags:
        - Data Product Versions
  /integration/data-products/v1/data-product/{product_id}/report-results/:
    get:
      description: Retrieves report results on the data product. Can be filtered by `report_key`.
      operationId: get_data_product_report_results
      parameters:
        - $ref: '#/components/parameters/product_id'
      responses:
        200:
          description: Data product reports found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductReportResults_READ'
        403:
          $ref: '#/components/responses/403_Error'
        404:
          $ref: '#/components/responses/404_Error'
      summary: Get data product reports
      tags:
        - Data Products
    post:
      description: Logs one or more report results for a data
      operationId: product_report_result
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductReportResults'
      parameters:
        - $ref: '#/components/parameters/product_id'
      responses:
        201:
          description: Report result(s) logged successfully
        403:
          $ref: '#/components/responses/403_Error'
        404:
          $ref: '#/components/responses/404_Error'
      summary: Log report results on a data product
      tags:
        - Data Products
  /integration/data-products/v1/marketplace/:
    get:
      description: Retrieves a list of data marketplaces
      operationId: list_data_marketplaces
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
      responses:
        200:
          description: Data marketplaces found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Marketplaces'
              examples:
                DataMarketplaces:
                  $ref: '#/components/examples/Marketplaces'
        403:
          $ref: '#/components/responses/403_Error'
      summary: Get all data marketplaces
      tags:
        - Data Marketplaces
    post:
      description: Creates a new data marketplace
      operationId: create_data_marketplace
      requestBody:
        content:
          application/x-yaml:
            schema:
              $ref: '#/components/schemas/MarketplaceBody'
            examples:
              NewDataMarketplace:
                $ref: '#/components/examples/MarketplaceBodyYaml'
          application/json:
            schema:
              $ref: '#/components/schemas/MarketplaceBody'
            examples:
              NewDataMarketplace:
                $ref: '#/components/examples/MarketplaceBody'
      responses:
        201:
          description: Data marketplace created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Marketplace'
              examples:
                DataMarketplace:
                  $ref: '#/components/examples/NewMarketplace'
        400:
          $ref: '#/components/responses/400_Error'
        403:
          $ref: '#/components/responses/403_Error'
      summary: Create a data marketplace
      tags:
        - Data Marketplaces
    put:
      description: Updates a specific data marketplace
      operationId: update_data_marketplace
      requestBody:
        content:
          application/x-yaml:
            schema:
              $ref: '#/components/schemas/MarketplaceBody'
            examples:
              NewDataMarketplace:
                $ref: '#/components/examples/MarketplaceBodyYaml'
          application/json:
            schema:
              $ref: '#/components/schemas/MarketplaceBody'
            examples:
              NewDataMarketplace:
                $ref: '#/components/examples/MarketplaceBody'
      responses:
        200:
          description: Data marketplace updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Marketplace'
              examples:
                DataMarketplace:
                  $ref: '#/components/examples/Marketplace'
        400:
          $ref: '#/components/responses/400_Error'
        403:
          $ref: '#/components/responses/403_Error'
        404:
          $ref: '#/components/responses/404_Error'
      summary: Update a data marketplace
      tags:
        - Data Marketplaces
  /integration/data-products/v1/marketplace/{marketplace_id}/:
    get:
      description: Retrieves details of a specific data marketplace
      operationId: get_data_marketplace
      parameters:
        - $ref: '#/components/parameters/marketplace_id'
      responses:
        200:
          description: Data marketplace found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Marketplace'
              examples:
                DataMarketplace:
                  $ref: '#/components/examples/Marketplace'
        403:
          $ref: '#/components/responses/403_Error'
        404:
          $ref: '#/components/responses/404_Error'
      summary: Get a specific data marketplace
      tags:
        - Data Marketplaces
    delete:
      description: Deletes a specific data marketplace
      operationId: delete_data_marketplace
      parameters:
        - $ref: '#/components/parameters/marketplace_id'
      responses:
        204:
          description: Data marketplace deleted successfully
        403:
          $ref: '#/components/responses/403_Error'
        404:
          $ref: '#/components/responses/404_Error'
      summary: Delete a data marketplace
      tags:
        - Data Marketplaces
  /integration/data-products/v1/marketplace/{marketplace_id}/data-product/:
    get:
      description: Retrieves a list of data products published in the given data marketplace
      operationId: list_published_data_products
      parameters:
        - $ref: '#/components/parameters/marketplace_id'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
      responses:
        200:
          description: Published data products found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataProductsWithMarketplaceInfo'
              examples:
                DataProducts:
                  $ref: '#/components/examples/DataProductsWithMarketplaceInfo'
        403:
          $ref: '#/components/responses/403_Error'
      summary: Get data products in a marketplace
      tags:
        - Data Products Publishing
  /integration/data-products/v1/marketplace/{marketplace_id}/data-product/{product_id}/:
    get:
      description: Retrieves a specific data product published in the given data marketplace
      operationId: get_published_data_product
      parameters:
        - $ref: '#/components/parameters/marketplace_id'
        - $ref: '#/components/parameters/product_id'
      responses:
        200:
          description: Published data product found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataProductWithMarketplaceInfo'
              examples:
                DataProduct:
                  $ref: '#/components/examples/DataProductWithMarketplaceInfo'
        403:
          $ref: '#/components/responses/403_Error'
        404:
          $ref: '#/components/responses/404_Error'
      summary: Get a specific data product in a marketplace
      tags:
        - Data Products Publishing
    post:
      description: Publishes a data product in the given data marketplace
      operationId: publish_data_product
      parameters:
        - $ref: '#/components/parameters/marketplace_id'
        - $ref: '#/components/parameters/product_id'
        - $ref: '#/components/parameters/version'
      responses:
        200:
          description: Data product published successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataProduct'
              examples:
                DataProduct:
                  $ref: '#/components/examples/DataProduct'
        403:
          $ref: '#/components/responses/403_Error'
        404:
          $ref: '#/components/responses/404_Error'
        422:
          description: Data product does not meet the standards set by the marketplace
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataProductStandardsFailure'
              examples:
                DataProductStandardsFailure:
                  $ref: '#/components/examples/DataProductStandardsFailure'

      summary: Publish a data product in a marketplace
      tags:
        - Data Products Publishing
    put:
      description: Updates a data product published in the given data marketplace
      operationId: update_published_data_product
      parameters:
        - $ref: '#/components/parameters/marketplace_id'
        - $ref: '#/components/parameters/product_id'
        - $ref: '#/components/parameters/version'
      responses:
        200:
          description: Data product updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataProduct'
              examples:
                DataProduct:
                  $ref: '#/components/examples/DataProduct'
        403:
          $ref: '#/components/responses/403_Error'
        404:
          $ref: '#/components/responses/404_Error'
      summary: Update a published data product in a marketplace
      tags:
        - Data Products Publishing
    delete:
      description: Unpublishes a data product from the given data marketplace
      operationId: unpublish_data_product
      parameters:
        - $ref: '#/components/parameters/marketplace_id'
        - $ref: '#/components/parameters/product_id'
      responses:
        204:
          description: Data product unpublished from the marketplace
        403:
          $ref: '#/components/responses/403_Error'
        404:
          $ref: '#/components/responses/404_Error'
      summary: Unpublish a data product from a marketplace
      tags:
        - Data Products Publishing
  /integration/data-products/v1/marketplace/{marketplace_id}/bulk-publish/:
    post:
      description: Updates, publishes, or unpublishes multiple data products in the given data marketplace
      operationId: bulk_publish_data_product
      parameters:
        - $ref: '#/components/parameters/marketplace_id'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkPublishInfo'
            examples:
              DataMarketplace:
                $ref: '#/components/examples/BulkPublishInfo'
      responses:
        200:
          description: Data products published/updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataProducts'
              examples:
                DataProducts:
                  $ref: '#/components/examples/DataProducts'
        400:
          $ref: '#/components/responses/400_Error'
        403:
          $ref: '#/components/responses/403_Error'
        404:
          $ref: '#/components/responses/404_Error'
      summary: Update data products in a marketplace
      tags:
        - Data Products Publishing
  #TODO: The endpoint is not supported in the UI now
  # /integration/data-products/v1/search-globally/:
  #   post:
  #     description: Perform a global search using a natural language query
  #     operationId: data_product_global_search
  #     requestBody:
  #       content:
  #         application/json:
  #           schema:
  #             $ref: '#/components/schemas/SearchQuery'
  #     responses:
  #       200:
  #         description: Data products found
  #         content:
  #           application/json:
  #             schema:
  #               $ref: '#/components/schemas/DataProducts'
  #             examples:
  #               DataProducts:
  #                 $ref: '#/components/examples/DataProducts'
  #       400:
  #         $ref: '#/components/responses/400_Error'
  #       403:
  #         $ref: '#/components/responses/403_Error'
  #     summary: Search for data products
  #     tags:
  #       - Data Products Search
  /integration/data-products/v1/data-product-check/:
    post:
      description: Test if a data product meets a set of standards
      operationId: check_data_product
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataProductCheck'
      responses:
        200:
          description: The result of the check of the data product against the standards
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataProductCheckResult'
        400:
          $ref: '#/components/responses/400_Error'
        403:
          $ref: '#/components/responses/403_Error'
        500:
          $ref: '#/components/responses/500_Error'
      summary: Check a data product against standards
      tags:
        - Data Products Publishing
  /integration/data-products/v1/report-results/:
    get:
      description: Retrieves report results on the data product. Can be filtered by `product_id` and/or `report_key`. Returns in reverse chronological order.
      operationId: get_report_results
      responses:
        200:
          description: Reports retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportResults_READ'
        403:
          $ref: '#/components/responses/403_Error'
        404:
          $ref: '#/components/responses/404_Error'
      summary: Get report results
      tags:
        - Data Products
    post:
      description: Logs one or more report results for multiple data products
      operationId: report_results
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReportResults'
      responses:
        201:
          description: Report result(s) logged successfully
        403:
          $ref: '#/components/responses/403_Error'
        404:
          $ref: '#/components/responses/404_Error'
      summary: Log report results on multiple data products
      tags:
        - Data Products

  /integration/data-products/v1/search-internally/{marketplace_id}/:
    post:
      description: Perform a search within a specific marketplace using a natural language query
      operationId: data_product_marketplace_search
      parameters:
        - $ref: '#/components/parameters/marketplace_id'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchQuery'
      responses:
        200:
          description: Data products found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataProductsWithMarketplaceInfo'
              examples:
                DataProducts:
                  $ref: '#/components/examples/DataProductsWithMarketplaceInfo'
        400:
          $ref: '#/components/responses/400_Error'
        403:
          $ref: '#/components/responses/403_Error'
      summary: Search for data products in a marketplace
      tags:
        - Data Products Search
  /integration/data-products/v1/data-products/permissions/:
    get:
      description: |
        Retrieves a list of permissions. Supports filtering by subject (user/group/everyone),
        object (app/marketplace/data_product), and role. If no filters are provided, all permissions are returned.

        *Note*: `subject_type` and `subject_id` must be provided together, likewise for `object_type` and `object_id`.
      operationId: list_permissions
      parameters:
        - in: query
          name: subject_type
          schema:
            $ref: '#/components/schemas/PermissionSubjectType'
          description: The users that the permissions apply to
        - in: query
          name: subject_id
          schema:
            type: string
          description: The ID of the user or group that the permissions apply to. If `subject_type` is `everyone`, must be `everyone`.
        - in: query
          name: object_type
          schema:
            $ref: '#/components/schemas/PermissionObjectType'
          description: The object type that the permissions apply to
        - in: query
          name: object_id
          schema:
            type: string
          description: The ID of the object that the permissions apply to
        - in: query
          name: role
          schema:
            $ref: '#/components/schemas/PermissionRole'
          description: The data products role that has been granted
      responses:
        200:
          description: Permissions list returned
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    subject_type:
                      $ref: '#/components/schemas/PermissionSubjectType'
                    subject_id:
                      type: string
                    object_type:
                      $ref: '#/components/schemas/PermissionObjectType'
                    object_id:
                      type: string
                    role:
                      $ref: '#/components/schemas/PermissionRole'
        400:
          $ref: '#/components/responses/400_Error'
        403:
          $ref: '#/components/responses/403_Error'
      summary: Get permissions (admin only)
      tags:
        - Permissions

    post:
      description: |
        Add a new permission.

        *Note*: The `target user` must have an appropriate license.
        If the license requirements for the *target user* are not met, a 403 response is returned with the message "User license insufficient for given role".
      operationId: create_permission
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - subject_type
                - subject_id
                - object_type
                - object_id
                - role
              properties:
                subject_type:
                  $ref: '#/components/schemas/PermissionSubjectType'
                subject_id:
                  type: string
                object_type:
                  $ref: '#/components/schemas/PermissionObjectType'
                object_id:
                  type: string
                role:
                  $ref: '#/components/schemas/PermissionRole'
      responses:
        201:
          description: Permission added successfully
        400:
          $ref: '#/components/responses/400_Error'
        403:
          $ref: '#/components/responses/403_Error'
      summary: Add permission (admin only)
      tags:
        - Permissions

    put:
      description: |
        Update an existing permission.

        *Note*: The `target user` must have an appropriate license.
        If the license requirements for the *target user* are not met, a 403 response is returned with the message "User license insufficient for given role".
      operationId: update_permission
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - subject_type
                - subject_id
                - object_type
                - object_id
                - role
              properties:
                subject_type:
                  $ref: '#/components/schemas/PermissionSubjectType'
                subject_id:
                  type: string
                object_type:
                  $ref: '#/components/schemas/PermissionObjectType'
                object_id:
                  type: string
                role:
                  $ref: '#/components/schemas/PermissionRole'
      responses:
        200:
          description: Permission updated successfully
        400:
          $ref: '#/components/responses/400_Error'
        403:
          $ref: '#/components/responses/403_Error'
      summary: Update permission (admin only)
      tags:
        - Permissions

    delete:
      description: Delete an existing permission.
      operationId: delete_permission
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - subject_type
                - subject_id
                - object_type
                - object_id
                - role
              properties:
                subject_type:
                  $ref: '#/components/schemas/PermissionSubjectType'
                subject_id:
                  type: string
                object_type:
                  $ref: '#/components/schemas/PermissionObjectType'
                object_id:
                  type: string
                role:
                  $ref: '#/components/schemas/PermissionRole'
      responses:
        204:
          description: Permission deleted successfully
        400:
          $ref: '#/components/responses/400_Error'
        403:
          $ref: '#/components/responses/403_Error'
      summary: Delete permission (admin only)
      tags:
        - Permissions
  /integration/data-products/v1/data-products/check-permissions/:
    get:
      operationId: check_user_permissions
      summary: Get all permissions assigned to the authenticated user
      description: >
        Retrieves all permissions assigned to the authenticated user, including group and 'everyone' permissions.
      responses:
        200:
          description: Permissions list for the current user
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    subject_type:
                      $ref: '#/components/schemas/PermissionSubjectType'
                    subject_id:
                      type: string
                    object_type:
                      $ref: '#/components/schemas/PermissionObjectType'
                    object_id:
                      type: string
                    role:
                      $ref: '#/components/schemas/PermissionRole'
        403:
          $ref: '#/components/responses/403_Error'
      tags:
        - Permissions

security:
  - ApiKeyAuth: []
servers:
  - url: '{protocol}://{base-url}'
    variables:
      protocol:
        default: http
        enum:
          - http
          - https
      base-url:
        default: localhost
        description: Alation BASE_URL setting for this instance

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: TOKEN
      description: API Key for user authentication

  #####
  # PARAMETERS
  #####

  parameters:
    limit:
      description: >
        The number of items to return
      in: query
      name: limit
      required: false
      schema:
        $ref: '#/components/schemas/Limit'
    offset:
      description: >
        The number of items to skip
      in: query
      name: skip
      required: false
      schema:
        $ref: '#/components/schemas/Offset'
    marketplace_id:
      description: Unique identifier of the data marketplace
      in: path
      name: marketplace_id
      required: true
      schema:
        type: string
      example: finance:public
    product_id:
      description: Unique identifier of the data product
      in: path
      name: product_id
      required: true
      schema:
        type: string
        example: finance:last_quarter_sales
    version_id:
      description: Unique identifier of the version of the data product
      in: path
      name: version_id
      required: true
      schema:
        type: string
      example: 1.0.0
    version:
      description: Unique identifier of the version of the data product, if not provided, the latest version is used
      in: query
      name: version
      required: false
      schema:
        type: string
      example: 1.0.0

  #####
  # SCHEMAS
  #####

  schemas:
    Limit:
      default: 100
      minimum: 1
      type: integer
    Offset:
      default: 0
      type: integer
    Error:
      type: object
      description: Properties of an Error Object
      properties:
        code:
          type: integer
          description: The HTTP status code
        detail:
          type: string
          description: More information about the error
      required:
        - code
        - detail
    DataProduct:
      type: object
      properties:
        product_id:
          type: string
          description: Unique identifier of the data product
        version_id:
          type: string
          description: Unique identifier of the data product version
        status:
          type: string
          description: Status of the data product (draft, ready)
        spec_json:
          $ref: '#/components/schemas/SpecJson'
        spec_yaml:
          type: string
          description: Specification of the data product
        ts_created:
          type: string
          description: Timestamp of when the data product was created
        ts_updated:
          type: string
          description: Timestamp of when the data product was last updated
    DataProducts:
      type: array
      items:
        $ref: '#/components/schemas/DataProduct'
    DataProductWithMarketplaceInfo:
      type: object
      allOf:
        - $ref: '#/components/schemas/DataProduct'
      properties:
        marketplace_context:
          type: object
          description: Additional information about the product in relation to the marketplace
          properties:
            badges:
              type: array
              items:
                $ref: 'data_products/standards_schema.yaml#/badges'
    DataProductsWithMarketplaceInfo:
      type: array
      items:
        $ref: '#/components/schemas/DataProductWithMarketplaceInfo'
    SpecJson:
      $ref: data_products/product_schema.yaml
    Marketplace:
      type: object
      description: Data marketplace where data products are published
      properties:
        external_marketplace_id:
          type: string
          description: Unique identifier of the markeplace
          example: market:finance
        spec:
          $ref: '#/components/schemas/MarketplaceBody'
        spec_yaml:
          type: string
          description: Specification of the data marketplace in YAML format
        products:
          type: array
          items:
            $ref: '#/components/schemas/DataProducts'
    MarketplaceBody:
      $ref: data_products/marketplace_schema.yaml
    Marketplaces:
      type: array
      items:
        $ref: '#/components/schemas/Marketplace'
    PublishInfo:
      type: object
      description: Information identifying the data product and its version
      properties:
        product_id:
          type: string
          description: Unique product identifier
        version_id:
          type: string
          description: Unique version identifier. If not provided, the latest version is used.
    BulkPublishInfo:
      type: object
      description: Information on publishing operations that should be performed in the marketplace
      properties:
        publish:
          type: array
          description: Information on data products that should be published (added) to the marketplace
          items:
            $ref: '#/components/schemas/PublishInfo'
        update:
          type: array
          description: Information on data products that should be updated in the marketplace. Used to update the version of published data products.
          items:
            $ref: '#/components/schemas/PublishInfo'
        unpublish:
          type: array
          description: Information on data products that should be unpublished (removed) from the marketplace
          items:
            $ref: '#/components/schemas/PublishInfo'
    SearchQuery:
      type: object
      description: Search query written in natural language. The query will be processed by AI.
      properties:
        user_query:
          type: string
          description: Natural language search query
          example: Which data products contain recent sales information?
    DataProductCheck:
      type: object
      description: A data product spec, and a set of standards to compare it to.
      properties:
        product_spec:
          $ref: '#/components/schemas/SpecJson'
        standards:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                enum:
                  - static
                description: The type of standard this is.
                example: static
              check:
                type: string
                description: A description of what the standard is checking for at the key given, written in natural language.
                example: Ensure that the product has a contact email.
              key:
                type: string
                description: The path to the attribute inside the product spec to evaluate the check against.
                example: 'product.owners'
    DataProductCheckResult:
      type: array
      description: The result of the check of the data product against the standards
      items:
        type: object
        properties:
          key:
            type: string
            description: The key that the standard was checking
            example: 'product.owners'
          check:
            type: string
            description: The description of the standard
            example: Ensure that the product has a contact email.
          type:
            type: string
            enum:
              - static
            description: The type of standard this is.
            example: static
          passed:
            type: boolean
            description: The result of the check. This is `true` if the check passed, and `false` if the check failed.
            example: true
          explanation:
            type: string
            description: An explanation of why the check passed or failed
            example: The product has a contact email attribute registered inside the 'owners' object
    DataProductStandardsFailure:
      type: array
      description: Explanations of the checks that failed
      items:
        type: string
    ProductReportResults:
      type: array
      description: A list of report results on a specific product
      items:
        $ref: '#/components/schemas/ProductReportResult'
    ProductReportResult:
      type: object
      description: A report result on a specific product
      properties:
        report_key:
          type: string
          description: The unique key that identifies the report.
          example: 'pii_found'
        value:
          description: The report result. Can be in any format.
          example: False
      additionalProperties: true
    ProductReportResults_READ:
      type: array
      description: A list of report results on a specific product
      items:
        $ref: '#/components/schemas/ProductReportResult_READ'
    ProductReportResult_READ:
      type: object
      description: A report result on a specific product
      allOf:
        - $ref: '#/components/schemas/ProductReportResult'
      properties:
        extra_fields:
          type: object
          description: Extra fields that were submitted with the report to add detail or context
          additionalProperties: true
    ReportResults:
      type: array
      description: A list of report results across any number of products
      items:
        $ref: '#/components/schemas/ReportResult'
    ReportResult:
      type: object
      description: A report result of a data product
      allOf:
        - $ref: '#/components/schemas/ProductReportResult'
      properties:
        product_id:
          type: string
          description: The product id of the product on which the result was reported
          example: 'na_revenue_by_year'
      additionalProperties: true
    ReportResults_READ:
      type: array
      description: A list of report results across any number of products
      items:
        $ref: '#/components/schemas/ReportResult_READ'
    ReportResult_READ:
      type: object
      description: The report result of a data product
      allOf:
        - $ref: '#/components/schemas/ProductReportResult_READ'
      properties:
        product_id:
          type: string
          description: The product id of the product on which the result was reported
          example: 'na_revenue_by_year'
        extra_fields:
          type: object
          description: Extra fields that were submitted with the report to add additional detail or context
          additionalProperties: true
    PermissionSubjectType:
      type: string
      description: Enum of possible permission subjects
      enum: ['everyone', 'user', 'group']
      example: 'user'
    PermissionObjectType:
      type: string
      description: Enum of possible objects that permission can be assigned to
      enum: ['app', 'data_product', 'markeplace']
      example: 'data_product'
    PermissionRole:
      type: string
      description: Enum of possible permission roles
      enum:
        [
          'app_admin',
          'app_user',
          'marketplace_admin',
          'marketplace_maintainer',
          'product_manager',
          'product_publisher',
          'product_admin',
          'viewer',
        ]
      example: 'viewer'

  #####
  # EXAMPLES
  #####

  examples:
    DataProduct:
      value:
        status: draft
        product_id: finance:last_quarter_sales
        spec_json:
          product:
            productId: finance:last_quarter_sales
            version: 1.0.0
            contactEmail: ann@mail.com
            contactName: Ann
            en:
              description: Data about Last Quarter Sales
              logoUrl: https://www.example.com/logo.png
              name: Last Quarter Sales
        spec_yaml: product details in the form of a yaml file
        ts_created: 2025-01-24T16:01:28.846071Z
        ts_updated: 2025-01-24T16:07:23.129600Z
        version_id: 1.0.0
    DataProductWithMarketplaceInfo:
      value:
        status: draft
        product_id: finance:last_quarter_sales
        spec_json:
          product:
            productId: finance:last_quarter_sales
            version: 1.0.0
            contactEmail: ann@mail.com
            contactName: Ann
            en:
              description: Data about Last Quarter Sales
              logoUrl: https://www.example.com/logo.png
              name: Last Quarter Sales
        spec_yaml: product details in the form of a yaml file
        ts_created: 2025-01-24T16:01:28.846071Z
        ts_updated: 2025-01-24T16:07:23.129600Z
        version_id: 1.0.0
        marketplace_context:
          badges:
            - check: The description of the product should describe where the data originated
              displayName:
                en: Origins
              key: product.description
              type: static
    DataProducts:
      value:
        - status: draft
          product_id: finance:last_quarter_sales
          spec_json:
            product:
              productId: finance:last_quarter_sales
              version: 1.0.0
              contactEmail: ann@mail.com
              contactName: Ann
              en:
                description: Data about Last Quarter Sales
                logoUrl: https://www.example.com/logo.png
                name: Last Quarter Sales
          spec_yaml: Product details in the form of a YAML file
          ts_created: 2025-01-24T16:01:28.846071Z
          ts_updated: 2025-01-24T16:07:23.129600Z
          version_id: 1.0.0
    DataProductsWithMarketplaceInfo:
      value:
        - status: draft
          product_id: finance:last_quarter_sales
          spec_json:
            product:
              productId: finance:last_quarter_sales
              version: 1.0.0
              contactEmail: ann@mail.com
              contactName: Ann
              en:
                description: Data about Last Quarter Sales
                logoUrl: https://www.example.com/logo.png
                name: Last Quarter Sales
          spec_yaml: Product details in the form of a YAML file
          ts_created: 2025-01-24T16:01:28.846071Z
          ts_updated: 2025-01-24T16:07:23.129600Z
          version_id: 1.0.0
          marketplace_context:
            badges:
              - check: The description of the product should describe where the data originated
                displayName:
                  en: Origins
                key: product.description
                type: static
    Marketplace:
      value:
        external_marketplace_id: finance:public
        name: Public Financial Data Products
        spec:
          marketplace:
            contactEmail: allie@alation.com
            contactName: Allie
            dataProductRequirementsSchema: {}
            en:
              description: Sales datasets including ARR, new sales, renewals, and churn.
              name: Sales Data
              shortDescription: Sales data marketplace
              heroImage: https://qualified-production.s3.us-east-1.amazonaws.com/uploads/2Ca2L9pzrcXKAgCEexjCT3basD8AJBUmsGAo/89ad0e768282f8a08e764b84216708c7bcec6dc1be660a8dfa8558c8cec8656b.png
            heroBackgroundColor: '#FFFFFF'
            marketplaceId: sales_marketplace
            badges:
              - check: The description of the product should describe where the data originated
                displayName:
                  en: Origins
                key: product.description
                type: static
            minimumStandard:
              - check: Product must have a contact email
                displayName:
                  en: Has a contact email
                key: product.contactEmail
                type: static
              - check: Has declared a support response time SLA in the description
                displayName:
                  en: Has a support SLA
                key: product.description
                type: static
        products:
          - status: ready
            product_id: finance:last_quarter_sales
            spec_json:
              product:
                productId: finance:last_quarter_sales
                version: 1.0.0
                contactEmail: ann@mail.com
                contactName: Ann
                en:
                  description: Data about Last Quarter Sales
                  logoUrl: https://www.example.com/logo.png
                  name: Last Quarter Sales
            spec_yaml: product details in the form of a YAML file
            ts_created: 2025-01-24T16:01:28.846071Z
            ts_updated: 2025-01-24T16:07:23.129600Z
            version_id: 1.0.0
    NewMarketplace:
      value:
        external_marketplace_id: finance:public
        spec:
          marketplace:
            contactEmail: allie@alation.com
            contactName: Allie
            dataProductRequirementsSchema: {}
            en:
              description: Sales datasets including ARR, new sales, renewals, and churn.
              name: Sales Data
              shortDescription: Sales data marketplace
              heroImage: https://qualified-production.s3.us-east-1.amazonaws.com/uploads/2Ca2L9pzrcXKAgCEexjCT3basD8AJBUmsGAo/89ad0e768282f8a08e764b84216708c7bcec6dc1be660a8dfa8558c8cec8656b.png
            heroBackgroundColor: '#FFFFFF'
            marketplaceId: sales_marketplace
            badges:
              - check: The description of the product should describe where the data originated
                displayName:
                  en: Origins
                key: product.description
                type: static
            minimumStandard:
              - check: Product must have a contact email
                displayName:
                  en: Has a contact email
                key: product.contactEmail
                type: static
              - check: Has declared a support response time SLA in the description
                displayName:
                  en: Has a support SLA
                key: product.description
                type: static
          products: []
        spec_yaml: |
          marketplace:
            contactEmail: allie@alation.com
            contactName: Allie
            dataProductRequirementsSchema: {}
            en:
              description: Sales datasets including ARR, new sales, renewals, and churn.
              name: Sales Data
              shortDescription: Sales data marketplace
              heroImage: https://qualified-production.s3.us-east-1.amazonaws.com/uploads/2Ca2L9pzrcXKAgCEexjCT3basD8AJBUmsGAo/89ad0e768282f8a08e764b84216708c7bcec6dc1be660a8dfa8558c8cec8656b.png
            heroBackgroundColor: "#FFFFFF"
            marketplaceId: sales_marketplace
            badges:
              - check: The description of the product should describe where the data originated
                displayName:
                  en: Origins
                key: product.description
                type: static
            minimumStandard:
              - check: Product must have a contact email
                displayName:
                  en: Has a contact email
                key: product.contactEmail
                type: static
              - check: Has declared a support response time SLA in the description
                displayName:
                  en: Has a support SLA
                key: product.description
                type: static
        products: []
    Marketplaces:
      value:
        - external_marketplace_id: finance:public
          spec:
            marketplace:
              contactEmail: allie@alation.com
              contactName: Allie
              dataProductRequirementsSchema: {}
              en:
                description: Sales datasets including ARR, new sales, renewals, and churn.
                name: Sales Data
                shortDescription: Sales data marketplace
                heroImage: https://qualified-production.s3.us-east-1.amazonaws.com/uploads/2Ca2L9pzrcXKAgCEexjCT3basD8AJBUmsGAo/89ad0e768282f8a08e764b84216708c7bcec6dc1be660a8dfa8558c8cec8656b.png
              heroBackgroundColor: '#FFFFFF'
              marketplaceId: sales_marketplace
              badges:
                - check: The description of the product should describe where the data originated
                  displayName:
                    en: Origins
                  key: product.description
                  type: static
              minimumStandard:
                - check: Product must have a contact email
                  displayName:
                    en: Has a contact email
                  key: product.contactEmail
                  type: static
                - check: Has declared a support response time SLA in the description
                  displayName:
                    en: Has a support SLA
                  key: product.description
                  type: static
              products: []
          spec_yaml: |
            marketplace:
              contactEmail: allie@alation.com
              contactName: Allie
              dataProductRequirementsSchema: {}
              en:
                description: Sales datasets including ARR, new sales, renewals, and churn.
                name: Sales Data
                shortDescription: Sales data marketplace
                heroImage: https://qualified-production.s3.us-east-1.amazonaws.com/uploads/2Ca2L9pzrcXKAgCEexjCT3basD8AJBUmsGAo/89ad0e768282f8a08e764b84216708c7bcec6dc1be660a8dfa8558c8cec8656b.png
              heroBackgroundColor: "#FFFFFF"
              marketplaceId: sales_marketplace
              badges:
                - check: The description of the product should describe where the data originated
                  displayName:
                    en: Origins
                  key: product.description
                  type: static
              minimumStandard:
                - check: Product must have a contact email
                  displayName:
                    en: Has a contact email
                  key: product.contactEmail
                  type: static
                - check: Has declared a support response time SLA in the description
                  displayName:
                    en: Has a support SLA
                  key: product.description
                  type: static
          products: []
    MarketplaceBody:
      value:
        marketplace:
          contactEmail: allie@alation.com
          contactName: Allie
          dataProductRequirementsSchema: {}
          en:
            description: Sales datasets including ARR, new sales, renewals, and churn.
            name: Sales Data
            shortDescription: Sales data marketplace
            heroImage: https://qualified-production.s3.us-east-1.amazonaws.com/uploads/2Ca2L9pzrcXKAgCEexjCT3basD8AJBUmsGAo/89ad0e768282f8a08e764b84216708c7bcec6dc1be660a8dfa8558c8cec8656b.png
          heroBackgroundColor: '#FFFFFF'
          marketplaceId: sales_marketplace
          badges:
            - check: The description of the product should describe where the data originated
              displayName:
                en: Origins
              key: product.description
              type: static
          minimumStandard:
            - check: Product must have a contact email
              displayName:
                en: Has a contact email
              key: product.contactEmail
              type: static
            - check: Has declared a support response time SLA in the description
              displayName:
                en: Has a support SLA
              key: product.description
              type: static
    MarketplaceBodyYaml:
      value: |
        marketplace:
          contactEmail: allie@alation.com
          contactName: Allie
          dataProductRequirementsSchema: {}
          en:
            description: Sales datasets including ARR, new sales, renewals, and churn.
            name: Sales Data
            shortDescription: Sales data marketplace
            heroImage: https://qualified-production.s3.us-east-1.amazonaws.com/uploads/2Ca2L9pzrcXKAgCEexjCT3basD8AJBUmsGAo/89ad0e768282f8a08e764b84216708c7bcec6dc1be660a8dfa8558c8cec8656b.png
          heroBackgroundColor: "#FFFFFF"
          marketplaceId: sales_marketplace
          badges:
            - check: The description of the product should describe where the data originated
              displayName:
                en: Origins
              key: product.description
              type: static
          minimumStandard:
            - check: Product must have a contact email
              displayName:
                en: Has a contact email
              key: product.contactEmail
              type: static
            - check: Has declared a support response time SLA in the description
              displayName:
                en: Has a support SLA
              key: product.description
              type: static
    ProductSpecJson:
      value:
        product:
          productId: finance:arr_sales_churn
          version: 1.0.0
          contactEmail: data-products@company.com
          contactName: Jane Doe
          en:
            name: ARR, Sales, and Churn
            shortDescription: Tracks ARR, new sales, renewals, and churn monthly
            description: >
              This data product provides visibility into financial metrics such as
              Annual Recurring Revenue (ARR), new sales, renewals, and churn. It is
              designed to help finance, sales, and executive teams monitor growth and
              retention performance across customer segments and time periods. Data is
              updated monthly and includes current and historical trends.
            logoUrl: https://example.com/logos/arr-sales-churn.png
          deliverySystems:
            snowflake:
              type: SQL
              uri: snowflake://acme.analytics/FINANCE/ARR_METRICS
              accessRequestInstruction:
                type: manual
                instruction: Request access via Snowflake role FINANCE_ANALYST or contact data-products@company.com
                request: https://company.com/access-request-form
          recordSets:
            arr_metrics_monthly:
              name: Monthly ARR Metrics
              description: >
                Each row represents monthly ARR metrics, including new sales, expansions,
                renewals, and churn, by customer segment.
              schema:
                - name: month
                  description: The month the metric applies to.
                  type: date
                - name: segment
                  description: Customer segment (e.g., Enterprise, SMB).
                  type: string
                - name: new_sales_arr
                  description: ARR from new customer sales in the month.
                  type: number
                - name: expansion_arr
                  description: ARR from existing customer expansions.
                  type: number
                - name: renewal_arr
                  description: ARR retained from renewals.
                  type: number
                - name: churn_arr
                  description: ARR lost due to customer churn.
                  type: number
                - name: net_new_arr
                  description: Net ARR change (sales + expansion + renewal - churn).
                  type: number
              sample:
                type: mock
                data: |
                  month,segment,new_sales_arr,expansion_arr,renewal_arr,churn_arr,net_new_arr
                  2024-01-01,Enterprise,120000,30000,100000,20000,230000
                  2024-01-01,SMB,50000,10000,40000,10000,90000
              dataAccess:
                - type: SQL
                  format: table
                  host: https://acme.snowflakecomputing.com
                  qualifiedName:
                    database: FINANCE
                    schema: ARR_METRICS
                    table: MONTHLY
                    column: month
                  documentationUrl: https://company.com/docs/arr-metrics
            customer_churn_details:
              name: Customer Churn Details
              description: >
                Each row represents a customer that churned in a given month,
                including associated ARR, churn reason, and segment. Useful for
                analyzing churn patterns at the customer level.
              schema:
                - name: customer_id
                  description: Unique customer identifier.
                  type: string
                - name: customer_name
                  description: The name of the customer.
                  type: string
                - name: churn_month
                  description: The month the customer churned.
                  type: date
                - name: churn_arr
                  description: ARR lost from this customer churn.
                  type: number
                - name: churn_reason
                  description: Reason for churn as captured by sales/support.
                  type: string
                - name: segment
                  description: Customer segment (e.g., Enterprise, SMB).
                  type: string
              sample:
                type: mock
                data: |
                  customer_id,customer_name,churn_month,churn_arr,churn_reason,segment
                  CUST123,Acme Corp,2024-01-01,50000,Budget cut,Enterprise
                  CUST456,Startify Inc,2024-01-01,10000,Switched to competitor,SMB
              dataAccess:
                - type: SQL
                  format: table
                  host: https://acme.snowflakecomputing.com
                  qualifiedName:
                    database: FINANCE
                    schema: ARR_METRICS
                    table: CUSTOMER_CHURN
                    column: customer_id
                  documentationUrl: https://company.com/docs/customer-churn
    ProductSpecYaml:
      value: |
        product:
          productId: finance:arr_sales_churn
          version: 1.0.0
          contactEmail: data-products@company.com
          contactName: Jane Doe
          en:
            name: ARR, Sales, and Churn
            shortDescription: Tracks ARR, new sales, renewals, and churn monthly
            description: >
              This data product provides visibility into financial metrics such as
              Annual Recurring Revenue (ARR), new sales, renewals, and churn. It is
              designed to help finance, sales, and executive teams monitor growth and
              retention performance across customer segments and time periods. Data is
              updated monthly and includes current and historical trends.
            logoUrl: https://example.com/logos/arr-sales-churn.png
          deliverySystems:
            snowflake:
              type: SQL
              uri: snowflake://acme.analytics/FINANCE/ARR_METRICS
              accessRequestInstruction:
                type: manual
                instruction: Request access via Snowflake role FINANCE_ANALYST or contact data-products@company.com
                request: https://company.com/access-request-form
          recordSets:
            arr_metrics_monthly:
              name: Monthly ARR Metrics
              description: >
                Each row represents monthly ARR metrics, including new sales, expansions,
                renewals, and churn, by customer segment.
              schema:
                - name: month
                  description: The month the metric applies to.
                  type: date
                - name: segment
                  description: Customer segment (e.g., Enterprise, SMB).
                  type: string
                - name: new_sales_arr
                  description: ARR from new customer sales in the month.
                  type: number
                - name: expansion_arr
                  description: ARR from existing customer expansions.
                  type: number
                - name: renewal_arr
                  description: ARR retained from renewals.
                  type: number
                - name: churn_arr
                  description: ARR lost due to customer churn.
                  type: number
                - name: net_new_arr
                  description: Net ARR change (sales + expansion + renewal - churn).
                  type: number
              sample:
                type: mock
                data: |
                  month,segment,new_sales_arr,expansion_arr,renewal_arr,churn_arr,net_new_arr
                  2024-01-01,Enterprise,120000,30000,100000,20000,230000
                  2024-01-01,SMB,50000,10000,40000,10000,90000
              dataAccess:
                - type: SQL
                  format: table
                  host: https://acme.snowflakecomputing.com
                  qualifiedName:
                    database: FINANCE
                    schema: ARR_METRICS
                    table: MONTHLY
                    column: month
                  documentationUrl: https://company.com/docs/arr-metrics
            customer_churn_details:
              name: Customer Churn Details
              description: >
                Each row represents a customer that churned in a given month,
                including associated ARR, churn reason, and segment. Useful for
                analyzing churn patterns at the customer level.
              schema:
                - name: customer_id
                  description: Unique customer identifier.
                  type: string
                - name: customer_name
                  description: The name of the customer.
                  type: string
                - name: churn_month
                  description: The month the customer churned.
                  type: date
                - name: churn_arr
                  description: ARR lost from this customer churn.
                  type: number
                - name: churn_reason
                  description: Reason for churn as captured by sales/support.
                  type: string
                - name: segment
                  description: Customer segment (e.g., Enterprise, SMB).
                  type: string
              sample:
                type: mock
                data: |
                  customer_id,customer_name,churn_month,churn_arr,churn_reason,segment
                  CUST123,Acme Corp,2024-01-01,50000,Budget cut,Enterprise
                  CUST456,Startify Inc,2024-01-01,10000,Switched to competitor,SMB
              dataAccess:
                - type: SQL
                  format: table
                  host: https://acme.snowflakecomputing.com
                  qualifiedName:
                    database: FINANCE
                    schema: ARR_METRICS
                    table: CUSTOMER_CHURN
                    column: customer_id
                  documentationUrl: https://company.com/docs/customer-churn
    BulkPublishInfo:
      value:
        publish:
          - product_id: new:product1
            version_id: 1.0.0
          - product_id: new:product2
            version_id: null
        update:
          - product_id: already:published:product
            version_id: 2.0.0
        unpublish:
          - product_id: deprecated:product
    DataProductStandardsFailure:
      value:
        - The product has no contact email attribute registered inside the 'owners' object
        - The product has no description attribute registered inside the 'en' object

  #####
  # RESPONSES
  #####

  responses:
    400_Error:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 400
            detail: 'Bad request'
    403_Error:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 403
            detail: 'Authentication failed'
    404_Error:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 404
            detail: 'Not found'
    500_Error:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 500
            detail: 'Internal server error'