---
title: "Update metadata for a dataset and a version"
method: PUT
path: "/datasets/{id}/editions/{edition}/versions/{version}/metadata"
tags: ["Private"]
---

# Update metadata for a dataset and a version

`PUT /datasets/{id}/editions/{edition}/versions/{version}/metadata`

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

## Path parameters

- `id` string, required
- `edition` string, required
- `version` string, required

## Headers

- `If-Match` string

## Request body

- Metadata — An object containing all metadata information against a version
  - `alerts` Alert[] — A list of alerts, for example corrections after the resource has been published
    - `date` string, date-time, required — The date and time of publication of the version
    - `description` string, required — Detail of what a user needs to be aware of for this dataset
    - `type` 'alert' | 'correction', required — 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.
  - `canonical_topic` string — **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.
  - `contacts` Contact[] — A list containing contact details of statisticians for a dataset
    - `email` string, email, required — Email address to contact the statistician or statistician group responsible for the dataset.
    - `name` string, required — The name of the statistician or statistician group contact point responsible for the dataset.
    - `telephone` string — Telephone number to contact the statistician or statistician group responsible for the dataset.
  - `dataset_id` string — The unique identifier for a dataset. The dataset ID cannot be changed once the series is first published.
  - `dataset_links` DatasetLinks — Navigational links related to the dataset resource to aid in API navigation.
    - `editions` object
      - `href` string — A URL to all editions for this dataset
    - `latest_version` LatestVersionLink — An object containing the latest version id and link
      - `href` string — A link to the latest version and edition of the dataset
      - `id` string — The unique id for the latest version of a dataset
    - `latest_edition` object — An object containing a link to the latest edition of the dataset.
      - `href` string — A link to the latest edition of the dataset.
    - `self` object — A link to this resource
      - `href` string — A URL to this resource
    - `taxonomy` object — The taxonomy path of the dataset's canonical topic.
      - `href` string — **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.
  - `description` string — A description for a dataset
  - `dimensions` Dimension[] — A list of codelists for each dimension of this version
    - `description` string
    - `dimension` string — The name of the dimension
    - `href` string — A link to the code-list entry for the dimension
    - `id` string — The id of the dimension
    - `is_area_type` boolean — Indicates if a dimension is an area-type (census datasets only)
    - `label` string
    - `links` object
      - `code_list` object — The code list related to this dimension
        - `href` string — A URL to the code list
        - `id` string — The unique id for the code list
      - `options` OptionsLink — A list of links related to this dimension
        - `href` string — A URL to a list of options for this dimension
      - `version` VersionLink — The dataset version this resource belongs to
        - `href` string — A URL to the version this resource relates to
        - `id` string — The version number this resource relates to
    - `number_of_options` integer — The number of options available for this dimension
    - `variable` string — The variable name (census datasets only)
  - `distribution` string[] — **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
  - `distributions` Distribution[] — A list of representations of the dataset available and how to access them.
    - `title` string, required — The title or label of the distribution.
    - `download_url` string, url, required — URL to directly download a file for the distribution in the specified format.
    - `byte_size` integer — The size in bytes of the download file referenced by `download_url`.
    - `format` 'csv' | 'sdmx' | 'xls' | 'xlsx' | 'csdb', required — The format for the download file referenced by `download_url`. Formats supported: * `csv` * `sdmx` * `xls` * `xlsx` * `csdb`
    - `media_type` 'text/csv' | 'application/vnd.sdmx.structurespecificdata+xml' | 'application/vnd.ms-excel' | 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' | 'text/plain' — 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)
  - `downloads` object — **Deprecated:** These fields have been deprecated and replaced by the `distributions` list. A selection of download objects containing information of downloadable files.
    - `csv` DownloadObject — Object containing information of a downloadable file
      - `href` string — The URL to the generated file
      - `size` string — The size of the file in bytes
    - `csvw` object — Object containing information of a downloadable file
      - `href` string — The URL to the generated file
      - `size` string — The size of the file in bytes
    - `txt` object — Object containing information of a downloadable file
      - `href` string — The URL to the generated file
      - `size` string — The size of the file in bytes
    - `xls` DownloadObject — Object containing information of a downloadable file
      - `href` string — The URL to the generated file
      - `size` string — The size of the file in bytes
  - `edition` string — The unique identifier for an edition of a dataset. The edition ID cannot be changed once first published. If a subsequent version of the edition attempts to change the edition ID, they will be treated as the first version of a new edition instead.
  - `edition_title` string — The human readable title of the edition.
  - `headers` string[] — A list of headers for a census dataset
  - `keywords` string[] — A list of keywords for a dataset
  - `last_updated` string, date-time — 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.
  - `latest_changes` LatestChange[] — A list of changes between version of an edition for a dataset and the previous version of the same dataset edition
    - `description` string — A description of what has changed between versions
    - `name` string — The title of the change that has occurred between versions
  - `license` string — The license the dataset is released under.
  - `links` MetadataLinks — A list of links related to this resource
    - `self` object — A link to this resource
      - `href` string — A URL to this resource
    - `version` VersionLink — The dataset version this resource belongs to
      - `href` string — A URL to the version this resource relates to
      - `id` string — The version number this resource relates to
    - `website_version` object — A link to the location of this version of the dataset on the web
      - `href` string — The uri to the location of this version of the dataset on the web
  - `methodologies` RelatedLink[] — A list of methodologies for the dataset.
    - `href` string, url, required — The url of the linked item.
    - `title` string, required — The title of the linked item.
    - `description` string — The description of the linked item.
  - `national_statistic` boolean — **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.
  - `next_release` string — 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.
  - `publications` RelatedLink[] — A list of publications related to this dataset.
    - `href` string, url, required — The url of the linked item.
    - `title` string, required — The title of the linked item.
    - `description` string — The description of the linked item.
  - `publishers` Publisher[] — A list of the publishers for the dataset.
    - `name` string, required — The name of the publisher
    - `href` string, url, required — A link to the publishers homepage
  - `state` 'created' | 'completed' | 'failed' | 'edition-confirmed' | 'associated' | 'published' — 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
  - `qmi` QMILink
    - `href` string, url, required — The url to the quality and methodology information sheet for the dataset.
  - `quality_designation` 'accredited-official' | 'official' | 'official-in-development' | 'no-accreditation' — The official statistics quality designation level of this dataset version. Possible quality designations: * `accredited-official` * `official` * `official-in-development` * `no-accreditation`
  - `related_content` RelatedLink[] — A list of website content related to this dataset.
    - `href` string, url, required — The url of the linked item.
    - `title` string, required — The title of the linked item.
    - `description` string — The description of the linked item.
  - `related_datasets` RelatedLink[] — A list of other datasets related to this dataset.
    - `href` string, url, required — The url of the linked item.
    - `title` string, required — The title of the linked item.
    - `description` string — The description of the linked item.
  - `release_date` string, date-time — The release date of this version of the dataset
  - `release_frequency` string — The release frequency of a dataset
  - `subtopics` string[] — **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.
  - `survey` string — The name of the survey the dataset was created from.
  - `title` string — The title of the dataset
  - `topics` string[] — 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` 'filterable' | 'cantabular_flexible_table' | 'cantabular_multivariate_table' | 'static' — 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.
  - `unit_of_measure` string — The unit of measure for the dataset observations
  - `usage_notes` UsageNote[] — A list of usage notes relating to the dataset
    - `title` string, required — The title of the usage note.
    - `note` string, required — The usage note text.
  - `version` integer — A number identifying the version for an edition from a dataset

## Response `200`

The editable metadata has been updated

## Other responses

- `400` — Invalid request, reasons can be one of the following: * invalid request body * version was incorrect
- `401` — Unauthorised to update metadata
- `403` — Unable to update resource, expected resource to have a state of associated
- `404` — Version was not found for a dataset using the id and edition provided
- `409` — Instance does not match the expected eTag
- `500` — Failed to process the request due to an internal error

---

[API](https://skmtc.net/office-of-national-statistics/apis/dataset-api.md) · [All operations](https://skmtc.net/office-of-national-statistics/apis/dataset-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/office-of-national-statistics/dataset-api/revisions/a2947a13d675/schema)