v1

latestOpenAPI 3.0.0Open Government Licence v3.02026-07-14355492.7 KB
Private

Update metadata for a dataset and a version

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

put/datasets/{id}/editions/{edition}/versions/{version}/metadata

Path parameters

idstring required

ID that represents a dataset

editionstring required

An edition of a dataset

versionstring required

A version of a dataset

Headers

If-Matchstring

Filter resource version, as returned by a previous ETag, to be validated; or '*' to skip the version check

Request body

canonical_topicstring

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.

dataset_idstring

The unique identifier for a dataset.

The dataset ID cannot be changed once the series is first published.

descriptionstring

A description for a dataset

distributionstring[]

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

editionstring

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_titlestring

The human readable title of the edition.

headersstring[]

A list of headers for a census dataset

keywordsstring[]

A list of keywords for a dataset

last_updatedstring 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.

licensestring

The license the dataset is released under.

national_statisticboolean

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_releasestring

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.

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
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
release_datestring date-time

The release date of this version of the dataset

release_frequencystring

The release frequency of a dataset

subtopicsstring[]

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.

surveystring

The name of the survey the dataset was created from.

titlestring

The title of the dataset

topicsstring[]

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_measurestring

The unit of measure for the dataset observations

versioninteger

A number identifying the version for an edition from a dataset

Example request

{
  "alerts": [
    {
      "description": "This is a description of the changes made as part of the correction or other important notice about this version.",
      "type": "correction"
    }
  ],
  "canonical_topic": "7779",
  "contacts": [
    {
      "email": "example@ons.gov.uk",
      "name": "Expert Statistical Team",
      "telephone": "+44 1234 111111"
    }
  ],
  "dataset_id": "my-dataset",
  "dataset_links": {
    "editions": {
      "href": "https://api.beta.ons.gov.uk/v1/datasets/my-dataset/editions"
    },
    "latest_version": {
      "href": "https://api.beta.ons.gov.uk/v1/datasets/my-dataset/editions/july-september-2017/versions/5",
      "id": "5"
    },
    "latest_edition": {
      "href": "https://api.beta.ons.gov.uk/v1/datasets/my-dataset/editions/july-september-2017"
    },
    "self": {
      "href": "https://api.beta.ons.gov.uk/v1/datasets/my-dataset"
    },
    "taxonomy": {
      "href": "https://www.ons.gov.uk/theme/topic"
    }
  },
  "description": "This dataset contains some very interesting data about the UK.",
  "dimensions": [
    {
      "links": {
        "version": {
          "href": "https://api.beta.ons.gov.uk/v1/datasets/my-dataset/editions/july-september-2017/versions/5",
          "id": "5"
        }
      }
    }
  ],
  "distribution": [
    "csv"
  ],
  "distributions": [
    {
      "title": "Full Dataset (CSV)",
      "download_url": "https://download.ons.gov.uk/my-dataset-download.csv",
      "byte_size": 4300000
    }
  ],
  "downloads": {
    "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"
    }
  },
  "edition": "july-september-2017",
  "edition_title": "July to September 2017",
  "headers": [
    "cantabular_table",
    "ltla",
    "ethnic_group_tb_8a"
  ],
  "keywords": [
    "Inflation"
  ],
  "latest_changes": [
    {
      "description": "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": "Data Suppression Changes"
    }
  ],
  "links": {
    "self": {
      "href": "https://api.beta.ons.gov.uk/v1/datasets/my-dataset/editions/july-september-2017/versions/5/metadata"
    },
    "version": {
      "href": "https://api.beta.ons.gov.uk/v1/datasets/my-dataset/editions/july-september-2017/versions/5",
      "id": "5"
    },
    "website_version": {
      "href": "https://www.ons.gov.uk/datasets/my-dataset/editions/july-september-2017/versions/5"
    }
  },
  "methodologies": [
    {
      "href": "https://www.ons.gov.uk/my-related-page",
      "title": "Related Link Title",
      "description": "This is a description of the linked resource."
    }
  ],
  "next_release": "To be announced",
  "publications": [
    {
      "href": "https://www.ons.gov.uk/my-related-page",
      "title": "Related Link Title",
      "description": "This is a description of the linked resource."
    }
  ],
  "state": "published",
  "qmi": {
    "href": "https://www.ons.gov.uk/businessindustryandtrade/retailindustry/methodologies/retailsalesindexrsiqmi"
  },
  "related_content": [
    {
      "href": "https://www.ons.gov.uk/my-related-page",
      "title": "Related Link Title",
      "description": "This is a description of the linked resource."
    }
  ],
  "related_datasets": [
    {
      "href": "https://www.ons.gov.uk/my-related-page",
      "title": "Related Link Title",
      "description": "This is a description of the linked resource."
    }
  ],
  "release_frequency": "Monthly",
  "subtopics": [
    "7755"
  ],
  "survey": "census",
  "title": "Consumer Prices Index",
  "topics": [
    "7779",
    "7755"
  ],
  "type": "static",
  "unit_of_measure": "Number of people",
  "usage_notes": [
    {
      "title": "Data Suppression",
      "note": "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."
    }
  ],
  "version": 1
}

Response

The editable metadata has been updated