swagger.yaml

swagger: "2.0"
info:
  description: |
    Dataset catalogue used to find information about data published by the ONS.

    `Datasets` are published in unique `versions`, which are categorized by `edition`. Data in each version is broken down by `dimensions`, and a unique combination of dimension `options` in a version can be used to retrieve `observation` level data.

    Note: As of the latest update, the `@context` field has been removed from all dataset endpoints to improve response performance and correct data structure."
  version: "1.0.0"
  title: "Explore our data"
  license:
    name: "Open Government Licence v3.0"
    url: "https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/"
basePath: "/v1"
tags:
  - name: "Public"
    description: Endpoints available on public API.
  - name: "Private"
    description: Internal only endpoints.
host: api.beta.ons.gov.uk
schemes:
  - "https"
parameters:
  dataset:
    name: dataset
    description: "A unique id for a dataset to filter on"
    in: query
    type: string
  dimension:
    name: dimension
    description: "A dimension from a dataset"
    in: path
    required: true
    type: string
  patch_options:
    required: true
    name: patch
    schema:
      $ref: "#/definitions/PatchOptions"
    description: "A list of patch operations for a dimension option"
    in: body
  patch_dimensions:
    required: true
    name: patch
    schema:
      $ref: "#/definitions/PatchDimensions"
    description: "A list of patch operations for a dimension"
    in: body
  edition:
    name: edition
    description: "An edition of a dataset"
    in: path
    required: true
    type: string
  event:
    name: event
    description: "An event that occurs when importing a dataset"
    in: body
    schema:
      $ref: "#/definitions/Event"
  dataset_id:
    name: id
    description: "ID that represents a dataset"
    in: path
    required: true
    type: string
  import_tasks:
    name: import_tasks
    description: "A request body to update the state of an import task"
    in: body
    schema:
      $ref: "#/definitions/ImportTasks"
  inserted_observations:
    name: inserted_observations
    description: "A value to increment the inserted_observations within an instance"
    in: path
    required: true
    type: integer
  instance_id:
    name: instance_id
    description: "A unique id for an instance"
    in: path
    required: true
    type: string
  instance:
    name: instance
    description: "An instance related to an import job and dataset"
    in: body
    required: true
    schema:
      $ref: "#/definitions/Instance"
  new_dataset:
    name: dataset
    description: "A new dataset"
    in: body
    required: true
    schema:
      $ref: "#/definitions/Dataset"
  new_version:
    name: new_version
    description: "A new version for an edition of a dataset"
    in: body
    required: true
    schema:
      $ref: "#/definitions/Version"
  node_id:
    name: node_id
    description: "An unique node id"
    in: path
    required: true
    type: string
  newInstance:
    name: instance
    description: "An instance related to an import job"
    in: body
    required: true
    schema:
      $ref: "#/definitions/NewInstance"
  option:
    name: option
    description: "A option to set within a type"
    in: path
    required: true
    type: string
  state:
    name: "state"
    description: "A comma separated list of state values to filter on (e.g. ‘completed,edition-confirmed’)"
    in: query
    type: string
  update_dataset:
    name: dataset
    description: "An update to a dataset"
    in: body
    required: true
    schema:
      $ref: "#/definitions/Dataset"
  update_dimension:
    name: dimension
    description: "A dimension object to update for a given instance"
    in: body
    required: true
    schema:
      $ref: "#/definitions/UpdateInstanceDimension"
  update_dimension_option_request:
    name: dimension_option
    description: "A dimension option from an instance"
    in: body
    schema:
      $ref: "#/definitions/UpdateDimensionOptionRequest"
  version:
    name: version
    description: "A version of a dataset"
    in: path
    required: true
    type: string
  version_update:
    name: version_update
    description: |
      Update to a version for an edition of a dataset.

      This model allows for the updating the deprecated `downloads` map for backwards compatability.
    in: body
    required: true
    schema:
      allOf:
        - $ref: "#/definitions/Version"
        - properties:
            downloads:
              allOf:
                - readOnly: false
  limit:
    name: limit
    description: "Maximum number of items that will be returned. A value of zero will return zero items."
    in: query
    required: false
    type: integer
    default: 20
    minimum: 0
    maximum: 1000
  offset:
    name: offset
    description: "Starting index of the items array that will be returned. By default it is zero, meaning that the returned items will start from the beginning."
    in: query
    required: false
    type: integer
    default: 0
    minimum: 0
  ids:
    name: id
    description: "List of ids, as comma separated values and/or as multiple query parameters with the same key (e.g. 'id=op1,op2&id=op3'). It defines the IDs that we want to retrieve. If provided, it takes precedence over offset and limit."
    in: query
    required: false
    type: string
  if_match:
    name: If-Match
    required: false
    description: "Filter resource version, as returned by a previous ETag, to be validated; or '*' to skip the version check"
    in: header
    type: string
  is_based_on:
    name: is_based_on
    required: false
    description: "A population type to search on to return datasets that are associated with that population type e.g. Usual-Residents.  This is applicable to Census 2021 datasets only."
    in: query
    type: string
  type:
    name: type
    required: false
    description: "A filter to search the datasets by dataset type e.g. type=static"
    in: query
    type: string
  metadata_update:
    name: metadata_update
    in: body
    required: true
    schema:
      $ref: "#/definitions/Metadata"
securityDefinitions:
  Authorization:
    name: Authorization
    description: "Access token provided by Auth Service in a Bearer format. Can be a human or service user token."
    in: header
    type: apiKey
  DownloadServiceAPIKey:
    name: X-Download-Service-Token
    description: "API key used to allow the download service to access public and private links to a download"
    in: header
    type: apiKey
paths:
  /datasets:
    get:
      tags:
        - "Public"
      summary: "List datasets"
      description: "Returns a list of all datasets available via the ONS APIs."
      parameters:
        - $ref: "#/parameters/is_based_on"
        - $ref: "#/parameters/type"
        - $ref: "#/parameters/limit"
        - $ref: "#/parameters/offset"
      security:
        - {}
        - Authorization: []
      produces:
        - "application/json"
      responses:
        200:
          description: "A json list containing datasets which have been published"
          schema:
            $ref: "#/definitions/Datasets"
          headers:
            ETag:
              description: The RFC7232 ETag header field the of the resource, where the resource is the response to the specific query paramaters. This is used for setting the `If-None-Match` headers on subsequent requests to check for changes.
              type: string
            Cache-Control:
              description: The RFC9111 Cache-Control header field for the response which instructs how to handle caching the resource.
              type: string
        400:
          description: "Parameter is_based_on or type was sent but no value was provided"
        404:
          description: "No dataset was found with the population-type provided"
        500:
          $ref: "#/responses/InternalError"
    post:
      tags:
        - "Private"
      summary: "Create a new dataset"
      description: "Allows an authenticated and authorised user to create a new dataset. The dataset ID should be included in the request body."
      parameters:
        - $ref: "#/parameters/new_dataset"
      security:
        - Authorization: []
      produces:
        - "application/json"
      responses:
        201:
          description: "A JSON object containing the newly created dataset"
          schema:
            $ref: "#/definitions/Dataset"
        400:
          description: "Invalid request body"
        401:
          description: "Unauthorised to create/overwrite dataset"
        403:
          description: "Forbidden to overwrite dataset, dataset already exists"
        500:
          $ref: "#/responses/InternalError"

  /datasets/{id}:
    post:
      tags:
        - "Private"
      summary: "Create a dataset (deprecated)"
      description: |
        **Deprecated:** This endpoint is being replaced by `POST /datasets`. Please use `POST /datasets` and provide the dataset ID in the request body. This endpoint may be removed in a future release.
      deprecated: true
      parameters:
        - $ref: "#/parameters/dataset_id"
        - $ref: "#/parameters/new_dataset"
      security:
        - Authorization: []
      produces:
        - "application/json"
      responses:
        201:
          description: "A json object containing a dataset which has been created"
          schema:
            $ref: "#/definitions/NewDatasetResponse"
        400:
          description: "Invalid request body"
        401:
          description: "Unauthorised to create/overwrite dataset"
        403:
          description: "Forbidden to overwrite dataset, already published"
        500:
          $ref: "#/responses/InternalError"
    get:
      tags:
        - "Public"
      summary: "Get a dataset"
      description: "The dataset contains all high level information, for additional details see editions or versions of a dataset. "
      parameters:
        - $ref: "#/parameters/dataset_id"
      security:
        - {}
        - Authorization: []
      responses:
        200:
          description: "A json object for a single Dataset"
          schema:
            $ref: "#/definitions/Dataset"
          headers:
            ETag:
              description: The RFC7232 ETag header field. Defines the unique entity tag for the current state of the resource. This is used for setting the `If-Match` and `If-None-Match` headers on subsequent requests.
              type: string
            Cache-Control:
              description: The RFC9111 Cache-Control header field for the response which instructs how to handle caching the resource.
              type: string
        404:
          description: "No dataset was found using the id provided"
        500:
          $ref: "#/responses/InternalError"
    put:
      tags:
        - "Private"
      summary: "Update a dataset"
      description: "Update the metadata for the next release of the dataset. The dataset contains all high level information, for additional details see editions or versions of a dataset."
      parameters:
        - $ref: "#/parameters/dataset_id"
        - $ref: "#/parameters/update_dataset"
      security:
        - Authorization: []
      responses:
        200:
          description: "A json object for a single Dataset"
        400:
          description: "Bad Request due to invalid json in the request body"
        401:
          description: "Unauthorised to update dataset"
        404:
          description: "No dataset was found using the id provided"
        500:
          $ref: "#/responses/InternalError"
    delete:
      tags:
        - "Private"
      summary: "Delete a dataset"
      description: "Delete an existing dataset"
      parameters:
        - $ref: "#/parameters/dataset_id"
      security:
        - Authorization: []
      responses:
        204:
          description: "The dataset was successfully deleted"
        401:
          description: "Unauthorised to delete the dataset"
        403:
          description: "Forbidden to delete dataset, already published"
        500:
          $ref: "#/responses/InternalError"
  /datasets/{id}/editions:
    get:
      tags:
        - "Public"
      summary: "Get a list of editions of a dataset"
      description: "Get a list of editions of a dataset. Each edition returns the latest version of that edition."
      parameters:
        - $ref: "#/parameters/dataset_id"
        - $ref: "#/parameters/limit"
        - $ref: "#/parameters/offset"
      security:
        - {}
        - Authorization: []
      responses:
        200:
          description: "A json list containing all editions for a dataset"
          schema:
            $ref: "#/definitions/Editions"
          headers:
            ETag:
              description: The RFC7232 ETag header field the of the resource, where the resource is the response to the specific query paramaters. This is used for setting the `If-None-Match` headers on subsequent requests to check for changes.
              type: string
            Cache-Control:
              description: The RFC9111 Cache-Control header field for the response which instructs how to handle caching the resource.
              type: string
        400:
          description: "Invalid request, dataset id was incorrect"
        404:
          description: "No editions were found for the id provided"
        500:
          $ref: "#/responses/InternalError"
  /datasets/{id}/editions/{edition}:
    get:
      tags:
        - "Public"
      summary: "Get an edition of a dataset"
      description: "Get the latest version of a dataset edition."
      parameters:
        - $ref: "#/parameters/edition"
        - $ref: "#/parameters/dataset_id"
      security:
        - {}
        - Authorization: []
      responses:
        200:
          description: "A json object containing the latest version of the edition"
          schema:
            $ref: "#/definitions/Version"
          headers:
            ETag:
              description: The RFC7232 ETag header field. Defines the unique entity tag for the current state of the resource. This is used for setting the `If-Match` and `If-None-Match` headers on subsequent requests.
              type: string
            Cache-Control:
              description: The RFC9111 Cache-Control header field for the response which instructs how to handle caching the resource.
              type: string
        400:
          description: "Invalid request, dataset id was incorrect"
        404:
          description: "No edition of a dataset was found using the id and edition provided"
        500:
          $ref: "#/responses/InternalError"
  /datasets/{id}/editions/{edition}/versions:
    get:
      tags:
        - "Public"
      summary: "List the edition's version history"
      description: "Get a list of all versions for a dataset edition."
      parameters:
        - $ref: "#/parameters/edition"
        - $ref: "#/parameters/dataset_id"
        - $ref: "#/parameters/limit"
        - $ref: "#/parameters/offset"
      security:
        - {}
        - Authorization: []
        - Authorization: []
          DownloadServiceAPIKey: []
      responses:
        200:
          description: "A json list containing all versions for a set type of dataset and edition"
          schema:
            $ref: "#/definitions/Versions"
          headers:
            ETag:
              description: The RFC7232 ETag header field the of the resource, where the resource is the response to the specific query paramaters. This is used for setting the `If-None-Match` headers on subsequent requests to check for changes.
              type: string
            Cache-Control:
              description: The RFC9111 Cache-Control header field for the response which instructs how to handle caching the resource.
              type: string
        400:
          description: |
            Invalid request, reasons can be one of the following:
              * dataset id was incorrect
              * edition was incorrect
        404:
          description: "No versions found using the id and edition provided"
        500:
          $ref: "#/responses/InternalError"
    post:
      tags:
        - "Private"
      summary: "Create a version"
      description: "Create a version for a dataset series.  This will set the state of the version and dataset series to be associated."
      parameters:
        - $ref: "#/parameters/dataset_id"
        - $ref: "#/parameters/edition"
        - $ref: "#/parameters/new_version"
      security:
        - {}
        - Authorization: []
      responses:
        201:
          description: "A json object containing a version"
          schema:
            $ref: "#/definitions/Version"
        400:
          description: |
            Invalid request, reasons can be one of the following:
              * invalid request body
              * dataset id was incorrect
              * edition was incorrect
              * an unpublished version of the dataset already exists
        401:
          description: "Unauthorised to update version of dataset"
        404:
          description: "Dataset series was not found for a dataset using the id and edition provided"
        500:
          $ref: "#/responses/InternalError"
  /datasets/{id}/editions/{edition}/versions/{version}:
    put:
      tags:
        - "Private"
      summary: "Update a version"
      description: "Update a version for an edition of a dataset, if the state is changed to associated or published, the parent documents(dataset and edition resources) will also be updated. A version can only be updated if the state is not published"
      parameters:
        - $ref: "#/parameters/dataset_id"
        - $ref: "#/parameters/edition"
        - $ref: "#/parameters/version"
        - $ref: "#/parameters/version_update"
      security:
        - Authorization: []
        - Authorization: []
          DownloadServiceAPIKey: []
      responses:
        201:
          description: "A json object containing a version"
          schema:
            $ref: "#/definitions/Version"
        400:
          description: |
            Invalid request, reasons can be one of the following:
              * invalid request body
              * dataset id was incorrect
              * edition was incorrect
        401:
          description: "Unauthorised to update version of dataset"
        403:
          description: "Forbidden to overwrite version of dataset, already published"
        404:
          description: "Version was not found for a dataset using the id and edition provided"
        500:
          $ref: "#/responses/InternalError"
    get:
      tags:
        - "Public"
      summary: "Get a specific version"
      description: "Get a specific version of an edition of a dataset"
      parameters:
        - $ref: "#/parameters/edition"
        - $ref: "#/parameters/dataset_id"
        - $ref: "#/parameters/version"
      security:
        - {}
        - Authorization: []
      responses:
        200:
          description: "A json object containing the edition and version of a dataset"
          schema:
            $ref: "#/definitions/Version"
          headers:
            ETag:
              description: The RFC7232 ETag header field. Defines the unique entity tag for the current state of the resource. This is used for setting the `If-Match` and `If-None-Match` headers on subsequent requests.
              type: string
            Cache-Control:
              description: The RFC9111 Cache-Control header field for the response which instructs how to handle caching the resource.
              type: string
        400:
          description: |
            Invalid request, reasons can be one of the following:
              * dataset id was incorrect
              * edition was incorrect
        404:
          description: "No version was found for an edition of a dataset using the id, edition and version provided"
        500:
          $ref: "#/responses/InternalError"
    delete:
      tags:
        - "Private"
      summary: "Delete a version"
      description: "detaches a version from a collection. Effectively a soft delete."
      parameters:
        - $ref: "#/parameters/edition"
        - $ref: "#/parameters/dataset_id"
        - $ref: "#/parameters/version"
      security:
        - Authorization: []
      responses:
        200:
          description: "A json object containing the edition and version of a dataset"
          schema:
            $ref: "#/definitions/Version"
        400:
          description: |
            Invalid request, reasons can be one of the following:
              * dataset id was incorrect
              * edition was incorrect
              * version state was incorrect
              * not the most recent unpublished version
        404:
          description: "No version was found for an edition of a dataset using the id, edition and version provided"
        500:
          $ref: "#/responses/InternalError"
  /datasets/{id}/editions/{edition}/versions/{version}/dimensions:
    get:
      tags:
        - "Public"
      summary: "Get a list of dimensions from a dataset (filterable and cantabular datasets only)"
      description: "Get all dimensions which are used in the dataset"
      parameters:
        - $ref: "#/parameters/edition"
        - $ref: "#/parameters/dataset_id"
        - $ref: "#/parameters/version"
        - $ref: "#/parameters/limit"
        - $ref: "#/parameters/offset"
      security:
        - {}
        - Authorization: []
      responses:
        200:
          description: "A json list of dimensions"
          schema:
            $ref: "#/definitions/Dimensions"
          headers:
            ETag:
              description: The RFC7232 ETag header field the of the resource, where the resource is the response to the specific query paramaters. This is used for setting the `If-None-Match` headers on subsequent requests to check for changes.
              type: string
            Cache-Control:
              description: The RFC9111 Cache-Control header field for the response which instructs how to handle caching the resource.
              type: string
        400:
          description: |
            Invalid request, reasons can be one of the following:
              * dataset id was incorrect
              * edition was incorrect
              * version was incorrect
        404:
          description: "No dimensions found for version of an edition of a dataset using the id, edition and version provided"
        500:
          $ref: "#/responses/InternalError"
  /datasets/{id}/editions/{edition}/versions/{version}/dimensions/{dimension}/options:
    get:
      tags:
        - "Public"
      summary: "Get a list of options from a dimension (filterable and cantabular datasets only)"
      description: "Get a list of options which appear in this dimension and dataset. By default all options are returned, but a subset can be requested by providing offset and limit query parameters, or by providing the list of option IDs, only the IDs that are found will be returned."
      parameters:
        - $ref: "#/parameters/dimension"
        - $ref: "#/parameters/edition"
        - $ref: "#/parameters/dataset_id"
        - $ref: "#/parameters/version"
        - $ref: "#/parameters/limit"
        - $ref: "#/parameters/offset"
        - $ref: "#/parameters/ids"
      security:
        - {}
        - Authorization: []
      responses:
        200:
          description: "Json object containing all options for a dimension"
          schema:
            $ref: "#/definitions/DimensionOptions"
          headers:
            ETag:
              description: The RFC7232 ETag header field the of the resource, where the resource is the response to the specific query paramaters. This is used for setting the `If-None-Match` headers on subsequent requests to check for changes.
              type: string
            Cache-Control:
              description: The RFC9111 Cache-Control header field for the response which instructs how to handle caching the resource.
              type: string
        400:
          description: |
            Invalid request, reasons can be one of the following:
              * dataset id was incorrect
              * edition was incorrect
              * version was incorrect
              * dimension was incorrect
              * query parameters incorrect offset provided
              * query parameters incorrect limit provided
        404:
          description: "No dimension options were found for dimension"
        500:
          $ref: "#/responses/InternalError"
  /datasets/{id}/editions/{edition}/versions/{version}/metadata:
    get:
      tags:
        - "Public"
      summary: "Get metadata for a version"
      description: "Get all metadata relevant to a version"
      parameters:
        - $ref: "#/parameters/edition"
        - $ref: "#/parameters/dataset_id"
        - $ref: "#/parameters/version"
      security:
        - {}
        - Authorization: []
      responses:
        200:
          description: "Json object containing all metadata for a version"
          schema:
            $ref: "#/definitions/Metadata"
          headers:
            ETag:
              description: The RFC7232 ETag header field. Defines the unique entity tag for the current state of the resource. This is used for setting the `If-Match` and `If-None-Match` headers on subsequent requests.
              type: string
            Cache-Control:
              description: The RFC9111 Cache-Control header field for the response which instructs how to handle caching the resource.
              type: string
        400:
          description: |
            Invalid request, reasons can be one of the following:
              * dataset id was incorrect
              * edition was incorrect
        404:
          description: "Version not found"
        500:
          $ref: "#/responses/InternalError"
    put:
      tags:
        - "Private"
      summary: "Update metadata for a dataset and a version"
      description: "Update metadata for a dataset and a version. The editable metadata can be updated only if both the dataset and the version have a state of associated"
      parameters:
        - $ref: "#/parameters/dataset_id"
        - $ref: "#/parameters/edition"
        - $ref: "#/parameters/version"
        - $ref: "#/parameters/if_match"
        - $ref: "#/parameters/metadata_update"
      security:
        - Authorization: []
      responses:
        200:
          description: "The editable metadata has been updated"
        400:
          description: |
            Invalid request, reasons can be one of the following:
              * invalid request body
              * version was incorrect
        401:
          description: "Unauthorised to update metadata"
        403:
          description: "Unable to update resource, expected resource to have a state of associated"
        404:
          description: "Version was not found for a dataset using the id and edition provided"
        409:
          description: "Instance does not match the expected eTag"
        500:
          $ref: "#/responses/InternalError"
  /instances:
    get:
      tags:
        - "Private"
      summary: "Get instances"
      description: "Get a list of instances which has been paged"
      parameters:
        - $ref: "#/parameters/state"
        - $ref: "#/parameters/dataset"
        - $ref: "#/parameters/limit"
        - $ref: "#/parameters/offset"
      produces:
        - "application/json"
      security:
        - Authorization: []
      responses:
        200:
          description: "Return a list of instance state"
          schema:
            $ref: "#/definitions/Instances"
          headers:
            ETag:
              description: The RFC7232 ETag header field. Defines the unique entity tag for the current state of the resource. This is used for setting the `If-Match` and `If-None-Match` headers on subsequent requests.
              type: string
            Cache-Control:
              description: The RFC9111 Cache-Control header field for the response which instructs how to handle caching the resource.
              type: string
        400:
          $ref: "#/responses/InvalidRequestError"
        401:
          $ref: "#/responses/UnauthorisedError"
        500:
          $ref: "#/responses/InternalError"
    post:
      tags:
        - "Private"
      summary: "Create an instance"
      description: |
        Create an instance which will be imported. To create an instance an import job id and href is required. This is to allow a link back to the import job
      parameters:
        - $ref: "#/parameters/newInstance"
      produces:
        - "application/json"
      security:
        - Authorization: []
      responses:
        201:
          description: "Successfully created instance"
          schema:
            $ref: "#/definitions/NewInstance"
          headers:
            ETag:
              type: string
              description: "Defines a unique instance resource version"
        400:
          $ref: "#/responses/InvalidRequestError"
        401:
          $ref: "#/responses/UnauthorisedError"
        403:
          $ref: "#/responses/ForbiddenError"
        500:
          $ref: "#/responses/InternalError"
  /instances/{instance_id}:
    get:
      tags:
        - "Private"
      summary: "Get an instance"
      description: "Get the current state of an instance, this includes all events which have happened."
      parameters:
        - $ref: "#/parameters/instance_id"
        - $ref: "#/parameters/if_match"
      produces:
        - "application/json"
      security:
        - Authorization: []
      responses:
        200:
          description: "Return a single instance state"
          schema:
            $ref: "#/definitions/Instance"
          headers:
            ETag:
              description: The RFC7232 ETag header field. Defines the unique entity tag for the current state of the resource. This is used for setting the `If-Match` and `If-None-Match` headers on subsequent requests.
              type: string
            Cache-Control:
              description: The RFC9111 Cache-Control header field for the response which instructs how to handle caching the resource.
              type: string
        401:
          $ref: "#/responses/UnauthorisedError"
        404:
          $ref: "#/responses/InstanceNotFound"
        409:
          $ref: "#/responses/ConflictError"
        500:
          $ref: "#/responses/InternalError"
    put:
      tags:
        - "Private"
      summary: "Update an instance"
      description: "Update an instance by providing an unique id and a set of properties to over write"
      parameters:
        - $ref: "#/parameters/instance_id"
        - $ref: "#/parameters/instance"
        - $ref: "#/parameters/if_match"
      produces:
        - "application/json"
      security:
        - Authorization: []
      responses:
        200:
          description: "The instance has been updated"
          headers:
            ETag:
              type: string
              description: "Defines a unique instance resource version"
        400:
          $ref: "#/responses/InvalidRequestError"
        401:
          $ref: "#/responses/UnauthorisedError"
        403:
          $ref: "#/responses/ForbiddenError"
        404:
          $ref: "#/responses/InstanceNotFound"
        409:
          $ref: "#/responses/ConflictError"
        500:
          $ref: "#/responses/InternalError"
  /instances/{instance_id}/dimensions:
    get:
      tags:
        - "Private"
      summary: "Get a list of dimensions for an instance"
      description: "Get all dimensions from an instance"
      parameters:
        - $ref: "#/parameters/instance_id"
        - $ref: "#/parameters/if_match"
      produces:
        - "application/json"
      security:
        - Authorization: []
      responses:
        200:
          description: "Return a list of dimensions"
          schema:
            type: array
            items:
              $ref: "#/definitions/DimensionOption"
          headers:
            ETag:
              description: The RFC7232 ETag header field. Defines the unique entity tag for the current state of the resource. This is used for setting the `If-Match` and `If-None-Match` headers on subsequent requests.
              type: string
            Cache-Control:
              description: The RFC9111 Cache-Control header field for the response which instructs how to handle caching the resource.
              type: string
        400:
          $ref: "#/responses/InvalidRequestError"
        401:
          $ref: "#/responses/UnauthorisedError"
        403:
          $ref: "#/responses/ForbiddenError"
        404:
          $ref: "#/responses/InstanceNotFound"
        409:
          $ref: "#/responses/ConflictError"
        500:
          $ref: "#/responses/InternalError"
    post:
      deprecated: true
      tags:
        - "Private"
      summary: "Create a dimension"
      description: "Create a new dimension which is related to an instance"
      parameters:
        - $ref: "#/parameters/instance_id"
        - $ref: "#/parameters/update_dimension_option_request"
        - $ref: "#/parameters/if_match"
      security:
        - Authorization: []
      responses:
        201:
          description: "Dimension was created"
          headers:
            ETag:
              type: string
              description: "Defines a unique instance resource version"
        400:
          $ref: "#/responses/InvalidRequestError"
        404:
          $ref: "#/responses/InstanceNotFound"
        409:
          $ref: "#/responses/ConflictError"
        500:
          $ref: "#/responses/InternalError"
    patch:
      tags:
        - "Private"
      summary: "Create one or more dimensions"
      description: "Create one or more dimensions which are related to an instance"
      parameters:
        - $ref: "#/parameters/instance_id"
        - $ref: "#/parameters/patch_dimensions"
        - $ref: "#/parameters/if_match"
      produces:
        - "application/json-patch+json"
      security:
        - Authorization: []
      responses:
        200:
          description: "All dimensions were successfully created"
          schema:
            $ref: "#/definitions/PatchDimensions"
          headers:
            ETag:
              type: string
              description: "Defines a unique instance resource version"
        400:
          $ref: "#/responses/InvalidRequestError"
        404:
          $ref: "#/responses/InstanceNotFound"
        409:
          $ref: "#/responses/ConflictError"
        500:
          $ref: "#/responses/InternalError"

  /instances/{instance_id}/dimensions/{dimension}:
    put:
      tags:
        - "Private"
      summary: "Update dimension"
      description: "Update the label and/or description of a dimension within an instance, by providing dimension name and properties to over write"
      parameters:
        - $ref: "#/parameters/instance_id"
        - $ref: "#/parameters/dimension"
        - $ref: "#/parameters/update_dimension"
        - $ref: "#/parameters/if_match"
      security:
        - Authorization: []
      responses:
        200:
          description: "The instance has been updated"
          headers:
            ETag:
              type: string
              description: "Defines a unique instance resource version"
        400:
          $ref: "#/responses/InvalidRequestError"
        401:
          $ref: "#/responses/UnauthorisedError"
        403:
          $ref: "#/responses/ForbiddenError"
        404:
          $ref: "#/responses/InstanceNotFound"
        409:
          $ref: "#/responses/ConflictError"
        500:
          $ref: "#/responses/InternalError"
  /instances/{instance_id}/dimensions/{dimension}/options:
    get:
      tags:
        - "Private"
      summary: "Get a list of options for a dimension"
      description: "Get all unique options from a dimension"
      parameters:
        - $ref: "#/parameters/instance_id"
        - $ref: "#/parameters/dimension"
        - $ref: "#/parameters/if_match"
      produces:
        - "application/json"
      security:
        - Authorization: []
      responses:
        200:
          description: "Return a list of unique options"
          schema:
            type: object
            properties:
              dimension:
                description: "The name of the dimension"
                type: string
              options:
                description: "A list of all unique options within a dimension"
                type: array
                items:
                  type: string
          headers:
            ETag:
              description: The RFC7232 ETag header field. Defines the unique entity tag for the current state of the resource. This is used for setting the `If-Match` and `If-None-Match` headers on subsequent requests.
              type: string
            Cache-Control:
              description: The RFC9111 Cache-Control header field for the response which instructs how to handle caching the resource.
              type: string
        400:
          $ref: "#/responses/InvalidRequestError"
        401:
          $ref: "#/responses/UnauthorisedError"
        403:
          $ref: "#/responses/ForbiddenError"
        404:
          description: "dimension does not match any dimensions within the instance"
        409:
          $ref: "#/responses/ConflictError"
        500:
          $ref: "#/responses/InternalError"
  /instances/{instance_id}/events:
    post:
      tags:
        - "Private"
      summary: "Add an event to an instance"
      description: |
        Add a new event into an instance. Events can be for information or error messages.
        Each event must contain a type of event (Info or Error), a message to explain
        the event, time of the event and finally the message offset in kafka
      parameters:
        - $ref: "#/parameters/instance_id"
        - $ref: "#/parameters/event"
        - $ref: "#/parameters/if_match"
      security:
        - Authorization: []
      responses:
        201:
          description: "The event was added to the instance"
          headers:
            ETag:
              type: string
              description: "Defines a unique instance resource version"
        400:
          $ref: "#/responses/InvalidRequestError"
        401:
          $ref: "#/responses/UnauthorisedError"
        404:
          description: "InstanceId does not match any instances"
        409:
          $ref: "#/responses/ConflictError"
        500:
          $ref: "#/responses/InternalError"
  /instances/{instance_id}/inserted_observations/{inserted_observations}:
    put:
      tags:
        - "Private"
      summary: "Increment the inserted observation count"
      description: "This will add to the number already store in the api"
      parameters:
        - $ref: "#/parameters/instance_id"
        - $ref: "#/parameters/inserted_observations"
        - $ref: "#/parameters/if_match"
      security:
        - Authorization: []
      responses:
        200:
          description: "Added value to inserted observation"
          headers:
            ETag:
              type: string
              description: "Defines a unique instance resource version"
        400:
          $ref: "#/responses/InvalidRequestError"
        401:
          $ref: "#/responses/UnauthorisedError"
        404:
          description: "InstanceId does not match any instances"
        409:
          $ref: "#/responses/ConflictError"
        500:
          $ref: "#/responses/InternalError"
  /instances/{instance_id}/import_tasks:
    put:
      tags:
        - "Private"
      summary: "Update import tasks for an instance"
      description: "The instance import process involves multiple tasks. This endpoint updates the state of an import task."
      parameters:
        - $ref: "#/parameters/instance_id"
        - $ref: "#/parameters/import_tasks"
        - $ref: "#/parameters/if_match"
      security:
        - Authorization: []
      responses:
        200:
          description: "Updated the state of the import task"
          headers:
            ETag:
              type: string
              description: "Defines a unique instance resource version"
        400:
          $ref: "#/responses/InvalidRequestError"
        401:
          $ref: "#/responses/UnauthorisedError"
        404:
          description: "InstanceId does not match any instances"
        409:
          $ref: "#/responses/ConflictError"
        500:
          $ref: "#/responses/InternalError"
  /instances/{instance_id}/dimensions/{dimension}/options/{option}:
    patch:
      tags:
        - "Private"
      summary: "Modify a dimension option for an instance"
      description: |
        Modify a dimension option for an instance by setting values for node_id or order
      parameters:
        - $ref: "#/parameters/instance_id"
        - $ref: "#/parameters/dimension"
        - $ref: "#/parameters/option"
        - $ref: "#/parameters/patch_options"
        - $ref: "#/parameters/if_match"
      produces:
        - "application/json-patch+json"
      security:
        - Authorization: []
      responses:
        200:
          description: "The dimension option was modified and the successfully applied patch operations are returned"
          schema:
            $ref: "#/definitions/PatchOptions"
          headers:
            ETag:
              type: string
              description: "Defines a unique instance resource version"
        400:
          $ref: "#/responses/InvalidRequestError"
        401:
          $ref: "#/responses/UnauthorisedError"
        403:
          $ref: "#/responses/ForbiddenError"
        404:
          description: "InstanceId does not match any instances"
        409:
          $ref: "#/responses/ConflictError"
        500:
          $ref: "#/responses/InternalError"
  /instances/{instance_id}/dimensions/{dimension}/options/{option}/node_id/{node_id}:
    put:
      deprecated: true
      tags:
        - "Private"
      summary: "Update a dimension with the node_id"
      description: |
        Update the dimension with a nodeId
      parameters:
        - $ref: "#/parameters/instance_id"
        - $ref: "#/parameters/dimension"
        - $ref: "#/parameters/node_id"
        - $ref: "#/parameters/option"
        - $ref: "#/parameters/if_match"
      produces:
        - "application/json"
      security:
        - Authorization: []
      responses:
        200:
          description: "Updated the dimension with the nodeId"
          headers:
            ETag:
              type: string
              description: "Defines a unique instance resource version"
        400:
          $ref: "#/responses/InvalidRequestError"
        401:
          $ref: "#/responses/UnauthorisedError"
        403:
          $ref: "#/responses/ForbiddenError"
        404:
          description: "InstanceId does not match any instances"
        409:
          $ref: "#/responses/ConflictError"
        500:
          $ref: "#/responses/InternalError"
responses:
  ConflictError:
    description: "Failed to process the request due to a conflict"
  ForbiddenError:
    description: "The request is forbidden"
  InstanceNotFound:
    description: "The instance was not found"
  InternalError:
    description: "Failed to process the request due to an internal error"
  InvalidRequestError:
    description: "Failed to process the request due to invalid request"
  UnauthorisedError:
    description: "The token provided is unauthorised to carry out this operation"
definitions:
  Alert:
    description: "Important notice relating to a version of a dataset"
    type: object
    required:
      - date
      - description
      - type
    properties:
      date:
        description: "The date and time of publication of the version"
        type: string
        format: date-time
      description:
        description: "Detail of what a user needs to be aware of for this dataset"
        type: string
        example: "This is a description of the changes made as part of the correction or other important notice about this version."
      type:
        description: |
          The type of alert.

          Available types:
            * `alert`: Important contextual information relevant to the interpretation of a specific version of the dataset.
            * `correction`: A correction notice summarising the data changes made in the corrected as compared to the superseded version.
        type: string
        enum:
          - alert
          - correction
        example: "correction"
  Codelist:
    type: object
    properties:
      href:
        description: "A link to the codelist corresponding to this dimension"
        type: string
      id:
        description: "The codelist id corresponding to this dimension"
        type: string
      name:
        description: "The dimension name"
        type: string
      description:
        description: "The dimension description"
        type: string
      label:
        description: "A human readable label for dimension"
        type: string
  CollectionID:
    description: |
      **Internal Only: This is an internal only field and is not present once a dataset is published.**

      The id of the unpublished collection (of datasets) that this dataset is associated with."
    type: string
    example: 666c06bc09d337ab9d164c82f8f383c081a4e38cbd91b79d4a23ea0025fecb3f
  Contact:
    description: "Statistical point of contact for the dataset."
    type: object
    required:
      - name
      - email
    properties:
      email:
        description: "Email address to contact the statistician or statistician group responsible for the dataset."
        type: string
        format: email
        example: "example@ons.gov.uk"
        pattern: "@ons\\.gov\\.uk$"
      name:
        description: "The name of the statistician or statistician group contact point responsible for the dataset."
        type: string
        example: "Expert Statistical Team"
      telephone:
        description: "Telephone number to contact the statistician or statistician group responsible for the dataset."
        type: string
        example: "+44 1234 111111"
        pattern: "^\\+44 (\\(0\\))?[1-9](\\d ?){8,10}$"
  DatasetID:
    description: |
      The unique identifier for a dataset.

      The dataset ID cannot be changed once the series is first published.
    example: "my-dataset"
    type: string
    minLength: 1
    maxLength: 100
    pattern: "^[a-z0-9]+(-[a-z0-9]+)*$"
  Datasets:
    description: "A list of datasets"
    type: object
    allOf:
      - $ref: "#/definitions/PaginationFields"
      - type: object
        properties:
          items:
            type: array
            items:
              $ref: "#/definitions/Dataset"
  Dataset:
    description: "The dataset"
    type: object
    required:
      - id
      - contacts
      - description
      - license
      - title
      - type
      - topics
    properties:
      id:
        $ref: "#/definitions/DatasetID"
      canonical_topic:
        description: |
          **Deprecated:** This field has been deprecated and replaced by the `topics` field.

          The canonical topic id for this dataset.  This indicates which topic this dataset belongs to within the topic taxonomy.
        type: string
        example: "7779"
      collection_id:
        $ref: "#/definitions/CollectionID"
      contacts:
        description: "A list containing contact details of statisticians for a dataset"
        type: array
        minItems: 1
        items:
          $ref: "#/definitions/Contact"
      description:
        description: "A description for a dataset"
        type: string
        example: "This dataset contains some very interesting data about the UK."
        minLength: 50
        maxLength: 5000
      is_based_on:
        $ref: "#/definitions/IsBasedOn"
      keywords:
        description: "A list of keywords for a dataset"
        type: array
        items:
          type: "string"
          example: "Inflation"
      last_updated:
        $ref: "#/definitions/LastUpdated"
      license:
        description: "The license the dataset is released under."
        type: string
        default: "Open Government Licence v3.0"
      links:
        readOnly: true
        $ref: "#/definitions/DatasetLinks"
      methodologies:
        description: "A list of methodologies for the dataset."
        type: array
        items:
          $ref: "#/definitions/RelatedLink"
      national_statistic:
        description: |
          **Deprecated:** This field has been deprecated and replaced with the `quality_designation` field under at the edition level in order to correctly represent the three potential quality designations under the updated Code of Practice for Statistics.

          The flag indicating the latest version of the dataset has `accredited` designation as granted under the Code of Practice for Statistics.
        type: boolean
      next_release:
        $ref: "#/definitions/NextRelease"
      publications:
        description: "A list of publications related to this dataset."
        type: array
        items:
          $ref: "#/definitions/RelatedLink"
      publishers:
        description: A list of the publishers for the dataset.
        type: array
        minLength: 1
        items:
          $ref: "#/definitions/Publisher"
        default:
          - name: Office for National Statistics
            href: https://www.ons.gov.uk
      qmi:
        $ref: "#/definitions/QMILink"
      related_datasets:
        description: "A list of other datasets related to this dataset."
        type: array
        items:
          $ref: "#/definitions/RelatedLink"
      related_content:
        description: "A list of website content related to this dataset."
        type: array
        items:
          $ref: "#/definitions/RelatedLink"
      release_frequency:
        description: "The release frequency of a dataset"
        type: string
        example: "Monthly"
      state:
        $ref: "#/definitions/State"
      subtopics:
        description: |
          **Deprecated:** This field is being deprecated and replaced by the `topics` field.

          A list of subtopic ids that the dataset relates to within the topic taxonomy.
        type: array
        items:
          type: "string"
          example: "7755"
      survey:
        description: "The name of the survey the dataset was created from."
        type: string
        example: "census"
      title:
        description: "The title of the dataset"
        example: "Consumer Prices Index"
        type: string
        minLength: 1
      topics:
        description: "A list of topic IDs that the dataset relates to within the topic taxonomy. This field consolidates the previously separate `canonical_topic` and `subtopics` fields."
        type: array
        minItems: 1
        items:
          type: "string"
        example: ["7779", "7755"]
      type:
        $ref: "#/definitions/DatasetType"
      unit_of_measure:
        description: "The unit of measure for the dataset observations"
        type: string
        example: "Number of people"
  LastUpdated:
    description: The date and time of the last update to the resource. For published resources this is the date and time the latest change was published.
    type: string
    format: date-time
    readOnly: true
  NextRelease:
    description: "The next release date for a dataset. This field is a free text field rather than a date-time format and may be a date range, to be confirmed or some other description."
    type: string
    example: "To be announced"
  DatasetType:
    description: |
      The type of dataset as determined by the backing data store. Used to determine which functionality is available for a dataset.

      Available types:
        * `filterable`: Datasets provided by Customise My Data product providing ability to filter observations by specific dimension options.
        * `cantabular_flexible_table`: Dataset derived from a `cantabular_blob` allowing the option to change the geography level and filter on specific areas.
        * `cantabular_multivariate_table`: Dataset with multiple variables derived from a `cantabular_blob` allowing the option to customise the dataset by adding or removing dimensions as well as by changing the geography level and dimension categorisation.
        * `static`: Datasets available as a flat file download without additional querying capabilities.
    type: string
    enum:
      - filterable
      - cantabular_flexible_table
      - cantabular_multivariate_table
      - static
    default: "filterable"
    example: "static"
  IsBasedOn:
    description: "Information about the population-type that the dataset is based on (census 2021 only)"
    type: object
    properties:
      id:
        description: "The population-type that the dataset is based on"
        type: string
        example: "Usual-Residents"
      type:
        description: "The type of the dataset"
        type: string
        example: "cantabular_table"
  Dimension:
    description: "A single dimension within a dataset"
    type: object
    properties:
      description:
        description: ""
        type: string
      dimension:
        description: "The name of the dimension"
        type: string
      href:
        description: "A link to the code-list entry for the dimension"
        type: string
      id:
        description: "The id of the dimension"
        type: string
      is_area_type:
        description: "Indicates if a dimension is an area-type (census datasets only)"
        type: boolean
      label:
        description: ""
        type: string
      links:
        type: object
        properties:
          code_list:
            description: "The code list related to this dimension"
            type: object
            properties:
              href:
                description: "A URL to the code list"
                type: string
              id:
                description: "The unique id for the code list"
                type: string
          options:
            $ref: "#/definitions/OptionsLink"
          version:
            $ref: "#/definitions/VersionLink"
      number_of_options:
        description: "The number of options available for this dimension"
        type: integer
      variable:
        description: "The variable name (census datasets only)"
        type: string
  Dimensions:
    description: "List of dimensions for a specific dataset version."
    type: object
    allOf:
      - $ref: "#/definitions/PaginationFields"
      - type: object
        properties:
          items:
            type: array
            items:
              $ref: "#/definitions/Dimension"
  DimensionOptions:
    description: "A list of options for a specific dimension."
    type: object
    allOf:
      - $ref: "#/definitions/PaginationFields"
      - type: object
        properties:
          items:
            type: array
            items:
              $ref: "#/definitions/DimensionOption"
  DimensionOption:
    type: object
    properties:
      dimension:
        description: "The name of the dimension"
        type: string
      instance_id:
        description: "The unique identifier for the instance in which this dimension option is associated to"
        type: string
      label:
        description: "A label given to a dimension option"
        type: string
      links:
        description: "A object with all resources related to a dimension option"
        type: object
        properties:
          code:
            description: "A link to the code of the dimension for this option"
            type: object
            properties:
              href:
                description: "The url of the code that refers to the dimension for this option"
                type: string
              id:
                description: "The id of the code that refers to the dimension for this option"
                type: string
          code_list:
            description: "A link to the code list the dimension for this option belongs to"
            type: object
            properties:
              href:
                description: "The url of the code list that the dimension for this option belongs to"
                type: string
              id:
                description: "The id of the code list that the dimension for this option belongs to"
                type: string
          version:
            description: "A link to the version of the dataset the option belongs to"
            readOnly: true
            type: object
            properties:
              href:
                description: "The href of the version that this option belongs to"
                type: string
              id:
                description: "The id of the version that this option belongs to"
                type: string
      node_id:
        description: "The id of the node"
        type: string
      option:
        description: "An option for a dimension"
        type: string
  PatchOptions:
    description: "A list of operations to patch a dimension option. Can only handle adding values for /node_id and /order. Each element in the array is processed in sequential order."
    type: array
    items:
      type: object
      description: "Item containing all necessary information to make a single operation on the resource."
      properties:
        op:
          description: |
            The operation to be made on path.
            * add - Sets the value for the provided path
          type: string
          enum: [add]
        path:
          description: "Path to value that needs to be operated on."
          type: string
          example: "/node_id"
          enum: [/node_id, /order]
        value:
          description: "A value that will be set for the provided path. /node_id accepts string values, and /order accepts integer values."
          example: "node_123"
  PatchDimensions:
    description: "A list of operations to patch dimensions. Can only handle adding lists of dimension values, and modifying order and node_id values for existing dimension options. The patch operations are executed in bulk to improve performance, and they are idempotent. If at least one of the provided dimensions and/or options in a patch path cannot be matched against existing dimension options, the request will fail with 404."
    type: array
    items:
      type: object
      description: "Item containing all necessary information to make a single operation on the resource."
      properties:
        op:
          description: |
            The operation to be made on path.
            * add - Sets the value for the provided path
          type: string
          enum: ["add"]
        path:
          description: "Path to value that needs to be operated on."
          type: string
          example: "/-"
          enum: ["/-", "/{dimension}/options/{option}/order", "/{dimension}/options/{option}/node_id"]
        value:
          description: "A list of dimensions that will be added to the instance."
          example: '[{"dimension": "dim1", "option": "op1"}, {"dimension": "dim1", "option": "op2"}, {"op": "add", "path": "/dim1/options/op1/order", "value": 3}, {"op": "add", "path": "/dim1/options/op2/node_id", "value": "node123"}]'
  DownloadObject:
    description: "Object containing information of a downloadable file"
    type: object
    properties:
      href:
        description: "The URL to the generated file"
        type: string
        example: https://download.ons.gov.uk/my-dataset-download.csv
      size:
        description: "The size of the file in bytes"
        type: string
        example: "466807"
  EditionID:
    description: |
      The unique identifier for an edition of a dataset.

      The edition ID cannot be changed once first published. Ifa subsequent version of the edition attempts to change the edition ID, they will be treated as the first version of a new edition instead.
    example: july-september-2017
    type: string
    minLength: 1
    maxLength: 100
    pattern: "^[a-z0-9]+(-[a-z0-9]+)*$"
  Editions:
    description: "A list of editions of a dataset."
    type: object
    allOf:
      - $ref: "#/definitions/PaginationFields"
      - type: object
        properties:
          items:
            type: array
            items:
              $ref: "#/definitions/Version"
  Event:
    type: object
    properties:
      message:
        description: "A description of the event"
        type: string
      message_offset:
        description: "The kafka message offset (Used to locate the kafka message)"
        type: string
      time:
        description: "The time of the event in ISO 8601 format"
        type: string
      type:
        description: |
          The type of event, this can be;
          * Info - for an information event
          * Error - for an error event
        type: string
  ImportTasks:
    type: object
    properties:
      build_hierarchies:
        type: array
        items:
          type: object
          properties:
            code_list_id:
              description: "The ID of the codelist that this hierarchy represents"
              type: string
            dimension_name:
              description: "The name of the dimension the hierarchy represents"
              type: string
            state:
              description: "The state of the import observations task"
              type: string
      build_search_indexes:
        type: array
        items:
          type: object
          properties:
            dimension_name:
              description: "The name of the dimension the search index represents"
              type: string
            state:
              description: "The state of the import observations task"
              type: string
      import_observations:
        type: object
        properties:
          state:
            description: "The state of the import observations task"
            type: string
          total_inserted_observations:
            description: "The number of inserted observations in this instance"
            type: integer
  Instance:
    type: object
    properties:
      alerts:
        description: "A list of alerts against an instance"
        readOnly: true
        type: array
        items:
          $ref: "#/definitions/Alert"
      id:
        description: "A unique id for an instance"
        readOnly: true
        type: string
      collection_id:
        $ref: "#/definitions/CollectionID"
      dimensions:
        description: "A list of codelists for each dimension of this instance"
        type: array
        items:
          $ref: "#/definitions/Codelist"
      downloads:
        description: "A selection of download objects containing information of downloadable files."
        type: object
        properties:
          csv:
            $ref: "#/definitions/DownloadObject"
          xls:
            $ref: "#/definitions/DownloadObject"
      edition:
        $ref: "#/definitions/EditionID"
      events:
        description: "A list of events took place for this job"
        readOnly: true
        type: array
        items:
          $ref: "#/definitions/Event"
      headers:
        description: "The header information from a V4 file"
        type: array
        items:
          type: string
      import_tasks:
        $ref: "#/definitions/ImportTasks"
      last_updated:
        description: "The last time an event happened"
        readOnly: true
        type: string
      links:
        type: object
        properties:
          dataset:
            description: "An object describing the ID and URL for a dataset which is associated with this instance"
            readOnly: true
            type: object
            properties:
              href:
                description: "The URL for the dataset associated with this instance"
                example: "https://api.beta.ons.gov.uk/v1/datasets/my-dataset"
                type: string
              id:
                $ref: "#/definitions/DatasetID"
          dimensions:
            description: "An object describing the URL for the dimensions which are associated with this instance"
            readOnly: true
            type: object
            properties:
              href:
                description: "The URL for a list of dimensions associated with this instance"
                example: "https://api.beta.ons.gov.uk/v1/datasets/my-dataset/editions/july-september-2017/versions/1/dimensions"
                type: string
          edition:
            description: "An object describing the ID and URL for the dataset edition that is associated with this instance"
            readOnly: true
            type: object
            properties:
              href:
                description: "The URL for the dataset edition associated with this instance"
                example: "https://api.beta.ons.gov.uk/v1/datasets/my-dataset/editions/july-september-2017"
                type: string
              id:
                $ref: "#/definitions/EditionID"
          job:
            description: "An object describing the ID and URL of the job containing this instance"
            readOnly: true
            required: ["id", "href"]
            type: object
            properties:
              href:
                description: "The URL for the job containing this instance"
                example: "https://api.beta.ons.gov.uk/v1/jobs/042e216a-7822-4fa0-a3d6-e3f5248ffc35"
                type: string
              id:
                description: "The ID of the job containing this instance"
                example: 042e216a-7822-4fa0-a3d6-e3f5248ffc35
                type: string
          self:
            description: "An object describing the ID and URL for a dataset which is associated with this instance"
            readOnly: true
            type: object
            properties:
              href:
                description: "The URL for this resource"
                example: "https://api.beta.ons.gov.uk/v1/instances/45c4669b-3ae9-4ba7-b690-87e890a1c67f"
                type: string
          version:
            description: "An object describing the ID and URL of the dataset version associated with this instance"
            readOnly: true
            type: object
            properties:
              href:
                description: "The URL for the dataset version associated with this instance"
                example: "https://api.beta.ons.gov.uk/v1/dataset/my-dataset/edition/july-september-2017/version/1"
                type: string
              id:
                description: "The ID of the dataset version associated with this instance"
                example: "1"
                type: string
      release_date:
        description: "The release date of this version of the dataset"
        type: string
        format: date-time
      state:
        $ref: "#/definitions/State"
      total_observations:
        description: "The number of observations in this instance"
        type: integer
      version:
        description: "The dataset version number that this instance is associated with, this will only be set once the state has been updated to `edition-confirmed`"
        readOnly: true
        type: integer
  Instances:
    description: "A list of instance resources, if query parameter state is set return all instances with that state"
    type: object
    allOf:
      - $ref: "#/definitions/PaginationFields"
      - type: object
        properties:
          items:
            type: array
            items:
              $ref: "#/definitions/Instance"
  LatestChange:
    description: "A single change between this version and the previous version of an edition for a dataset"
    type: object
    properties:
      description:
        description: "A description of what has changed between versions"
        type: string
        example: Some estimates for the periods between April 2011 and March 2019 have been updated. This is because of changes in guidance on suppressing data, where estimates are no longer required to be suppressed solely based on their co-efficient of variation (CV) values.
      name:
        description: "The title of the change that has occurred between versions"
        type: string
        example: "Data Suppression Changes"
  Metadata:
    description: "An object containing all metadata information against a version"
    type: object
    properties:
      alerts:
        description: "A list of alerts, for example corrections after the resource has been published"
        type: array
        items:
          $ref: "#/definitions/Alert"
      canonical_topic:
        description: |
          **Deprecated:** This field has been deprecated and replaced by the `topics` field.

          The canonical topic id for this dataset.  This indicates which topic this dataset belongs to within the topic taxonomy.
        type: string
        example: "7779"
      contacts:
        description: "A list containing contact details of statisticians for a dataset"
        type: array
        minItems: 1
        items:
          $ref: "#/definitions/Contact"
      dataset_id:
        allOf:
          - readOnly: true
          - $ref: "#/definitions/DatasetID"
      dataset_links:
        readOnly: true
        $ref: "#/definitions/DatasetLinks"
      description:
        description: "A description for a dataset"
        type: string
        example: "This dataset contains some very interesting data about the UK."
        minLength: 50
        maxLength: 5000
      dimensions:
        description: "A list of codelists for each dimension of this version"
        type: array
        items:
          $ref: "#/definitions/Dimension"
      distribution:
        description: |
          **Deprecated:** This field is being deprecated. Use `distributions` for list of formats in which the dataset can be accessed.

          A list of media types that the version data of an edition of a dataset can be accessed
        type: array
        readOnly: true
        items:
          type: string
          example: csv
      distributions:
        description: A list of representations of the dataset available and how to access them.
        type: array
        readOnly: true
        minItems: 1
        items:
          $ref: "#/definitions/Distribution"
      downloads:
        allOf:
          - readOnly: true
          - $ref: "#/definitions/VersionDownloads"
      edition:
        allOf:
          - readOnly: true
          - $ref: "#/definitions/EditionID"
      edition_title:
        description: The human readable title of the edition.
        type: string
        example: July to September 2017
      headers:
        description: "A list of headers for a census dataset"
        type: array
        readOnly: true
        items:
          type: "string"
        example:
          - cantabular_table
          - ltla
          - ethnic_group_tb_8a
      keywords:
        description: "A list of keywords for a dataset"
        type: array
        items:
          type: "string"
          example: "Inflation"
      last_updated:
        $ref: "#/definitions/LastUpdated"
      latest_changes:
        description: "A list of changes between version of an edition for a dataset and the previous version of the same dataset edition"
        type: array
        items:
          $ref: "#/definitions/LatestChange"
      license:
        description: "The license the dataset is released under."
        type: string
        default: "Open Government Licence v3.0"
      links:
        $ref: "#/definitions/MetadataLinks"
      methodologies:
        description: "A list of methodologies for the dataset."
        type: array
        items:
          $ref: "#/definitions/RelatedLink"
      national_statistic:
        description: |
          **Deprecated:** This field has been deprecated and replaced with the `quality_designation` field under at the edition level in order to correctly represent the three potential quality designations under the updated Code of Practice for Statistics.

          The flag indicating the latest version of the dataset has `accredited` designation as granted under the Code of Practice for Statistics.
        type: boolean
      next_release:
        $ref: "#/definitions/NextRelease"
      publications:
        description: "A list of publications related to this dataset."
        type: array
        items:
          $ref: "#/definitions/RelatedLink"
      publishers:
        description: A list of the publishers for the dataset.
        type: array
        items:
          $ref: "#/definitions/Publisher"
      qmi:
        $ref: "#/definitions/QMILink"
      quality_designation:
        description: |
          The official statistics quality designation level of this dataset version.

          Possible quality designations:
            * `accredited-official`
            * `official`
            * `official-in-development`
        type: string
        enum:
          - accredited-official
          - official
          - official-in-development
      related_content:
        description: "A list of website content related to this dataset."
        type: array
        items:
          $ref: "#/definitions/RelatedLink"
      related_datasets:
        description: "A list of other datasets related to this dataset."
        type: array
        items:
          $ref: "#/definitions/RelatedLink"
      release_date:
        description: "The release date of this version of the dataset"
        type: string
        format: date-time
      release_frequency:
        description: "The release frequency of a dataset"
        type: string
        example: "Monthly"
      subtopics:
        description: |
          **Deprecated:** This field is being deprecated and replaced by the `topics` field.

          A list of subtopic ids that the dataset relates to within the topic taxonomy.
        type: array
        items:
          type: "string"
          example: "7755"
      survey:
        description: "The name of the survey the dataset was created from."
        type: string
        example: census
      title:
        description: "The title of the dataset"
        example: "Consumer Prices Index"
        type: string
      topics:
        description: "A list of topic IDs that the dataset relates to within the topic taxonomy. This field consolidates the previously separate `canonical_topic` and `subtopics` fields."
        type: array
        minItems: 1
        items:
          type: "string"
        example: ["7779", "7755"]
      type:
        allOf:
          - readOnly: true
          - $ref: "#/definitions/DatasetType"
      unit_of_measure:
        description: "The unit of measure for the dataset observations"
        type: string
        example: "Number of people"
      usage_notes:
        description: "A list of usage notes relating to the dataset"
        type: array
        items:
          $ref: "#/definitions/UsageNote"
      version:
        description: "A number identifying the version for an edition from a dataset"
        example: 1
        readOnly: true
        type: integer
  NewDatasetResponse:
    description: "A model for the response body when creating a new dataset"
    type: object
    properties:
      id:
        description: "An unique database id for a dataset"
        example: "DE3BC0B6-D6C4-4E20-917E-95D7EA8C91DC"
        type: string
      current:
        allOf:
          - type: object
            properties:
              collection_id:
                $ref: "#/definitions/CollectionID"
              type:
                $ref: "#/definitions/DatasetType"
          - $ref: "#/definitions/Dataset"
      next:
        allOf:
          - type: object
            properties:
              collection_id:
                $ref: "#/definitions/CollectionID"
              type:
                $ref: "#/definitions/DatasetType"
          - $ref: "#/definitions/Dataset"
  NewInstance:
    description: "A model for the request and response body for creating a new instance"
    type: object
    properties:
      dimensions:
        description: "A list of codelists for each dimension of this instance"
        type: array
        items:
          $ref: "#/definitions/Codelist"
      id:
        description: "A unique id for an instance"
        readOnly: true
        type: string
      import_tasks:
        $ref: "#/definitions/ImportTasks"
      links:
        type: object
        readOnly: true
        properties:
          dataset:
            description: "An object describing the ID and URL for a dataset which is associated with this instance"
            type: object
            properties:
              href:
                description: "The URL for the dataset associated with this instance"
                example: "https://api.beta.ons.gov.uk/v1/datasets/my-dataset"
                type: string
              id:
                $ref: "#/definitions/DatasetID"
          job:
            description: "An object describing the ID and URL of the job containing this instance"
            required: ["id", "href"]
            type: object
            properties:
              href:
                description: "The URL for the job containing this instance"
                example: "https://api.beta.ons.gov.uk/v1/jobs/042e216a-7822-4fa0-a3d6-e3f5248ffc35"
                type: string
              id:
                description: "The ID of the job containing this instance"
                example: 042e216a-7822-4fa0-a3d6-e3f5248ffc35
                type: string
          self:
            description: "An object describing the ID and URL for a dataset which is associated with this instance"
            readOnly: true
            type: object
            properties:
              href:
                description: "The URL for this resource"
                example: "https://api.beta.ons.gov.uk/v1/instances/45c4669b-3ae9-4ba7-b690-87e890a1c67f"
                type: string
      state:
        $ref: "#/definitions/State"
  Publisher:
    description: "The publisher of the dataset"
    type: object
    required:
      - name
      - href
    properties:
      name:
        description: "The name of the publisher"
        type: string
        minLength: 1
        default: Office for National Statistics
      href:
        description: "A link to the publishers homepage"
        type: string
        minLength: 1
        format: url
        default: "https://www.ons.gov.uk"
  State:
    description: |
      The state of the resource, can only be one of the following:
        * created
        * completed (instances only)
        * failed (instances only)
        * edition-confirmed (instances and versions only)
        * associated (not editions)
        * published
    type: string
    example: published
    enum:
      - created
      - completed
      - failed
      - edition-confirmed
      - associated
      - published
  UpdateDatasetResponse:
    description: "A model for the response body when creating a new dataset"
    type: object
    properties:
      id:
        description: "An unique database ID for a dataset"
        example: "DE3BC0B6-D6C4-4E20-917E-95D7EA8C91DC"
        type: string
      current:
        allOf:
          - type: object
            properties:
              collection_id:
                $ref: "#/definitions/CollectionID"
          - $ref: "#/definitions/Dataset"
      next:
        allOf:
          - type: object
            properties:
              collection_id:
                $ref: "#/definitions/CollectionID"
          - $ref: "#/definitions/Dataset"
  UpdateDimensionOptionRequest:
    description: "A cached dimension. (Only used by the Private API)"
    type: object
    properties:
      code:
        description: ""
        type: string
      codelist:
        description: ""
        type: string
      dimension:
        description: "The name of the dimension"
        type: string
      instance_id:
        description: "The unique identifier for the instance in which this dimension option is associated to"
        type: string
      label:
        description: "The label for a option"
        type: string
      option:
        description: "The option of the dimension"
        type: string
      order:
        description: "The numerical order for the dimension option"
        type: integer
  UpdateDownloadObject:
    description: "Object containing information of a downloadable file"
    type: object
    properties:
      href:
        description: "The URL to the generated file"
        type: string
      size:
        description: "The size of the file in bytes"
        type: string
      public:
        description: "The URL to a public-accessible download"
        type: string
      private:
        description: "The URL to a non public-accessible download"
        type: string
  UpdateInstanceDimension:
    description: "Possible fields to be updated against a dimension for an instance resource"
    type: object
    properties:
      description:
        description: "The dimension description"
        type: string
      label:
        description: "A human readable label for dimension"
        type: string
  UsageNote:
    description: Essential usage information a user needs to be aware of when interpreting the data.
    type: object
    required:
      - title
      - note
    properties:
      title:
        description: The title of the usage note.
        type: string
        example: Data Suppression
      note:
        description: The usage note text.
        type: string
        example: Individual estimates suppressed with "[c]" relate to statistics based on a small number of respondents (< 5). Such values have been suppressed on quality grounds and to maintain confidentiality.
  Versions:
    description: "A list of version history for a specific dataset edition."
    type: object
    allOf:
      - $ref: "#/definitions/PaginationFields"
      - type: object
        properties:
          items:
            type: array
            items:
              $ref: "#/definitions/Version"
  Version:
    description: "An object containing information about published datasets from the ONS"
    required:
      - distributions
      - release_date
      - edition_title
    type: object
    properties:
      alerts:
        description: "A list of alerts, for example corrections after the resource has been published"
        type: array
        items:
          $ref: "#/definitions/Alert"
      collection_id:
        $ref: "#/definitions/CollectionID"
      dataset_id:
        allOf:
          - readOnly: true
          - $ref: "#/definitions/DatasetID"
      dimensions:
        description: "A list of codelists for each dimension of this version"
        type: array
        readOnly: true
        items:
          $ref: "#/definitions/Dimension"
      distributions:
        description: A list of representations of the dataset available and how to access them.
        type: array
        minItems: 1
        items:
          $ref: "#/definitions/Distribution"
      downloads:
        allOf:
          - readOnly: true
          - $ref: "#/definitions/VersionDownloads"
      edition:
        allOf:
          - readOnly: true
          - $ref: "#/definitions/EditionID"
      edition_title:
        description: The human readable title of the edition.
        type: string
        minLength: 1
        example: July to September 2017
      is_based_on:
        $ref: "#/definitions/IsBasedOn"
      last_updated:
        $ref: "#/definitions/LastUpdated"
      latest_changes:
        description: "A list of changes between version of an edition for a dataset and the previous version of the same dataset edition"
        type: array
        items:
          $ref: "#/definitions/LatestChange"
      links:
        $ref: "#/definitions/VersionLinks"
      lowest_geography:
        description: |
          The lowest geography this dataset is available at (Census datasets only)

          Possible geographies:
            * `oa`: Output Areas
            * `lsoa`: Lower layer Super Output Areas
            * `msoa`: Middle layer Super Output Areas
            * `wpc`: Westminster Parliamentary constituencies
            * `ltla`: Lower Tier Local Authorities
            * `rgn`: Regions
        type: string
        enum:
          - oa
          - lsoa
          - msoa
          - wpc
          - ltla
          - rgn
      quality_designation:
        description: |
          The official statistics quality designation level of this dataset version.

          Possible quality designations:
            * `accredited-official`
            * `official`
            * `official-in-development`
        type: string
        enum:
          - accredited-official
          - official
          - official-in-development
      release_date:
        description: "The release date of this version of the dataset"
        type: string
        format: date-time
      state:
        $ref: "#/definitions/State"
      type:
        readOnly: true
        allOf:
          - $ref: "#/definitions/DatasetType"
      usage_notes:
        description: "A list of usage notes relating to the dataset"
        type: array
        items:
          $ref: "#/definitions/UsageNote"
      version:
        description: "A number identifying the version for an edition from a dataset"
        example: 1
        readOnly: true
        type: integer
  VersionDownloads:
    description: |
      **Deprecated:** These fields have been deprecated and replaced by the `distributions` list.

      A selection of download objects containing information of downloadable files.
    type: object
    properties:
      csv:
        $ref: "#/definitions/DownloadObject"
      csvw:
        allOf:
          - readOnly: true
          - $ref: "#/definitions/DownloadObject"
      txt:
        allOf:
          - readOnly: true
          - $ref: "#/definitions/DownloadObject"
      xls:
        $ref: "#/definitions/DownloadObject"
    example:
      csv:
        href: https://download.ons.gov.uk/my-dataset-download.csv
        size: "123456"
      csvw:
        href: https://download.ons.gov.uk/my-dataset.metadata.json
        size: "123456"
      txt:
        href: https://download.ons.gov.uk/my-dataset.metadata.txt
        size: "123456"
      xls:
        href: https://download.ons.gov.uk/my-dataset.xls
        size: "123456"
  Distribution:
    description: The details of specific representation of a dataset and how to access it.
    type: object
    required:
      - title
      - format
      - download_url
    properties:
      title:
        description: The title or label of the distribution.
        type: string
        minLength: 1
        example: Full Dataset (CSV)
      download_url:
        description: URL to directly download a file for the distribution in the specified format.
        type: string
        format: url
        minLength: 1
        pattern: "^(/.+|https://[^/]+\\.ons\\.gov\\.uk/.+)"
        example: https://download.ons.gov.uk/my-dataset-download.csv
      byte_size:
        description: The size in bytes of the download file referenced by `download_url`.
        type: integer
        minimum: 0
        example: 4300000
        readOnly: true
      format:
        description: |
          The format for the download file referenced by `download_url`.

          Formats supported:
            * `csv`
            * `sdmx`
            * `xls`
            * `xlsx`
            * `csdb`
        type: string
        enum:
          - csv
          - sdmx
          - xls
          - xlsx
          - csdb
      media_type:
        description: |
          The IANA media type for the download file referenced by `download_url`.

          Media Types supported:
            * `text/csv`: CSV files
            * `application/vnd.sdmx.structurespecificdata+xml`: SDMX files
            * `application/vnd.ms-excel`: Excel (XLS) files
            * `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`: Excel (XLSX) files
            * `text/plain`: Plain text (used for CSDB output structured text files)
        type: string
        readOnly: true
        enum:
          - text/csv
          - application/vnd.sdmx.structurespecificdata+xml
          - application/vnd.ms-excel
          - application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
          - text/plain
  # Link objects
  DatasetLinks:
    description: "Navigational links related to the dataset resource to aid in API navigation."
    type: object
    readOnly: true
    properties:
      editions:
        readOnly: true
        type: object
        properties:
          href:
            description: "A URL to all editions for this dataset"
            type: string
            example: "https://api.beta.ons.gov.uk/v1/datasets/my-dataset/editions"
      latest_version:
        $ref: "#/definitions/LatestVersionLink"
      latest_edition:
        description: "An object containing a link to the latest edition of the dataset."
        type: object
        readOnly: true
        properties:
          href:
            description: "A link to the latest edition of the dataset."
            type: string
            example: "https://api.beta.ons.gov.uk/v1/datasets/my-dataset/editions/july-september-2017"
      self:
        description: "A link to this resource"
        readOnly: true
        type: object
        properties:
          href:
            description: "A URL to this resource"
            type: string
            example: "https://api.beta.ons.gov.uk/v1/datasets/my-dataset"
      taxonomy:
        description: "The taxonomy path of the dataset's canonical topic."
        type: object
        readOnly: true
        properties:
          href:
            description: |
              **Deprecated:** This field has been deprecated and will be removed in future. It is strongly advised that you do not use this field as topics will move in the hierarchy and therefore the value returned here will become outdated. Use the first entry in the `topics` list in combination with the Topics API instead.

              The taxonomy path of the canonical topic for the dataset at the time of publish.
            type: string
            example: https://www.ons.gov.uk/theme/topic
  MetadataLinks:
    description: "A list of links related to this resource"
    readOnly: true
    type: object
    properties:
      self:
        description: "A link to this resource"
        readOnly: true
        type: object
        properties:
          href:
            description: "A URL to this resource"
            type: string
            example: "https://api.beta.ons.gov.uk/v1/datasets/my-dataset/editions/july-september-2017/versions/5/metadata"
      version:
        $ref: "#/definitions/VersionLink"
      website_version:
        description: "A link to the location of this version of the dataset on the web"
        type: object
        readOnly: true
        properties:
          href:
            description: "The uri to the location of this version of the dataset on the web"
            type: string
            example: "https://www.ons.gov.uk/datasets/my-dataset/editions/july-september-2017/versions/5"
  VersionLinks:
    description: "A list of links related to this resource"
    type: object
    readOnly: true
    properties:
      dataset:
        $ref: "#/definitions/DatasetLink"
      dimensions:
        readOnly: true
        type: object
        properties:
          href:
            description: "A URL to list dimensions for this version"
            example: "https://api.beta.ons.gov.uk/v1/datasets/my-dataset/editions/july-september-2017/versions/5/dimensions"
            type: string
      edition:
        $ref: "#/definitions/EditionLink"
      self:
        description: "A link to this resource"
        readOnly: true
        type: object
        properties:
          href:
            description: "A URL to this resource"
            type: string
            example: "https://api.beta.ons.gov.uk/v1/datasets/my-dataset/editions/july-september-2017/versions/5"
      versions:
        type: object
        readOnly: true
        properties:
          href:
            description: "A URL to all versions for an edition of a dataset"
            example: "https://api.beta.ons.gov.uk/v1/datasets/my-dataset/edition/july-september-2017/versions"
            type: string
  DatasetLink:
    description: "An object containing the dataset id and link"
    readOnly: true
    type: object
    properties:
      href:
        description: "A URL to the parent dataset for this resource"
        example: "https://api.beta.ons.gov.uk/v1/datasets/my-dataset"
        type: string
      id:
        $ref: "#/definitions/DatasetID"
  EditionLink:
    description: "An object containing the edition and link"
    readOnly: true
    type: object
    properties:
      href:
        description: "A URL to the dataset edition for a version"
        example: "https://api.beta.ons.gov.uk/v1/datasets/my-datasets/editions/july-september-2017"
        type: string
      id:
        description: "The unique id for the dataset edition for a version"
        type: string
        example: "july-september-2017"
  LatestVersionLink:
    description: "An object containing the latest version id and link"
    type: object
    readOnly: true
    properties:
      href:
        description: "A link to the latest version and edition of the dataset"
        example: "https://api.beta.ons.gov.uk/v1/datasets/my-dataset/editions/july-september-2017/versions/5"
        type: string
      id:
        description: "The unique id for the latest version of a dataset"
        type: "string"
        example: "5"
  MetadataLink:
    description: "The version metadata that is associated with this resource"
    type: object
    readOnly: true
    properties:
      href:
        description: "A URL for the version metadata this resource relates to"
        type: string
  OptionsLink:
    description: "A list of links related to this dimension"
    type: object
    readOnly: true
    properties:
      href:
        description: "A URL to a list of options for this dimension"
        type: string
  VersionLink:
    description: "The dataset version this resource belongs to"
    type: object
    readOnly: true
    properties:
      href:
        description: "A URL to the version this resource relates to"
        type: string
        example: "https://api.beta.ons.gov.uk/v1/datasets/my-dataset/editions/july-september-2017/versions/5"
      id:
        description: "The version number this resource relates to"
        type: string
        example: "5"
  RelatedLink:
    type: object
    required:
      - href
      - title
    properties:
      href:
        description: "The url of the linked item."
        type: string
        example: "https://www.ons.gov.uk/my-related-page"
        format: url
        pattern: "^(/.+|https://[^/]+\\.ons\\.gov\\.uk/.+)"
      title:
        description: "The title of the linked item."
        type: string
        minLength: 1
        example: "Related Link Title"
      description:
        description: "The description of the linked item."
        type: string
        example: "This is a description of the linked resource."
  QMILink:
    type: object
    required:
      - href
    properties:
      href:
        description: "The url to the quality and methodology information sheet for the dataset."
        type: string
        format: url
        pattern: "^(/.+|https://[^/]+\\.ons\\.gov\\.uk/.+)"
        example: "https://www.ons.gov.uk/businessindustryandtrade/retailindustry/methodologies/retailsalesindexrsiqmi"
  PaginationFields:
    type: object
    properties:
      count:
        description: "The number of items returned."
        readOnly: true
        type: integer
        example: 20
      limit:
        description: "The number of items requested."
        type: integer
        default: 20
        minimum: 0
        maximum: 1000
      offset:
        description: "The offset of the first item to retrieve, starting at 0. Use this parameter as a pagination mechanism along with the limit parameter"
        type: integer
        example: 0
        default: 0
      total_count:
        description: "The total number of items available."
        readOnly: true
        type: integer
        example: 123