Beta This is a new service – your feedback will help us to improve it.

General

Publishers

Developers

API endpoints

Update dataset

Updates a dataset resource by identifier.

Implements JSON Merge Patch https://www.rfc-editor.org/rfc/rfc7396

PATCH /datasets/{dataset-id}

Parameters

dataset-id
string

The identifier of the dataset to be retrieved.

Request body

title
string max length: 200

The full and formal name given to an information resource. A name given to the distribution.

type
string

Values: Data Set, Data Service, Data Group, Data Share

Topic: A controlled term that expresses the broad topical content of an information resource. Subject: A controlled term that expresses a topic of the intellectual content of an information resource.

accessRights
string

Values: RESTRICTED, OPEN, COMMERCIAL, INTERNAL

A rights statement that concerns how the distribution is accessed.

contactPoint
array of objects

Contact information

Object parameters:

name string

email string

role string

created
date time string
creator
string max length: 75

The organisation responsible for creating the catalogued resource.

description
string max length: 4096

A concise narrative of the content of an catalogued resource.

identifier
string max length: 50

A unique number, code, or reference value assigned to a catalogued resource within the catalogue.

issued
date time string
license
object

A legal document under which the resource is made available.

keyword
array of strings

Uncontrolled terms (words or phrases) assigned to describe an information resource.

modified
date time string
publisher
string max length: 75

The entity responsible for making the catalogued resource publicly available.

securityClassification
string

Values: OFFICIAL, SECRET, TOP_SECRET, NOT_APPLICABLE

An information security designation that identifies the minimum level of protection assigned to an information resource.

status
string

Values: Draft, Published, Withdrawn, Deleted

Lifecycle status of resource within catalogue

supplierIdentifier
string max length: 50

A unique number, code, or reference value assigned to a catalogued resource a third party (supplier's) system.

theme
array of strings

Topic: A controlled term that expresses the broad topical content of an information resource. Subject: A controlled term that expresses a topic of the intellectual content of an information resource.

distribution
array of objects

A collection of distributions

Object parameters:

accessService array of strings

A reference to the service that provided the data

accessURL string

The location from which the Dataset can be accessed. To be used instead of downloadURL when describing an API

description string

Human readable description of the distribution

downloadURL string

The location from which the Dataset can be downloaded or Web Page accessed (when mediaType text/html)

format string

Human readable description of the format of the data provided by the distribution

mediaType array of strings

The IANA media type, or file format, type, or extention, of the distribution file.

title string

A title for the distribution

updateFrequency
string

The schedule for how often the data is updated

Examples

Add a new keyword

                {
  "keyword": [
    "Air travel",
    "Passport",
    "Airports",
    "leaving UK",
    "entering UK",
    "New keyword here!"
  ]
};

Change the contact point name

                {
  "contactPoint": [
    {
      "name": "Tom Redfern",
      "email": "tom.redfern@digital.cabinet-office.gov.uk",
      "role": "contact"
    }
  ]
};

Responses

200

Success

application/json

object

title
string

The full and formal name given to an information resource. A name given to the distribution.

type
string

Topic: A controlled term that expresses the broad topical content of an information resource. Subject: A controlled term that expresses a topic of the intellectual content of an information resource.

accessRights
string

A rights statement that concerns how the distribution is accessed.

contactPoint
array of objects

Contact information

created
date time string
creator
string

The organisation responsible for creating the catalogued resource.

description
string

A concise narrative of the content of an catalogued resource.

identifier
string

A unique number, code, or reference value assigned to a catalogued resource within the catalogue.

issued
date time string
license
object

A legal document under which the resource is made available.

keyword
array of strings

Uncontrolled terms (words or phrases) assigned to describe an information resource.

modified
date time string
publisher
string

The entity responsible for making the catalogued resource publicly available.

securityClassification
string

An information security designation that identifies the minimum level of protection assigned to an information resource.

status
string

Lifecycle status of resource within catalogue

supplierIdentifier
string

A unique number, code, or reference value assigned to a catalogued resource a third party (supplier's) system.

theme
array of strings

Topic: A controlled term that expresses the broad topical content of an information resource. Subject: A controlled term that expresses a topic of the intellectual content of an information resource.

distribution
array of objects

A collection of distributions

updateFrequency
string

The schedule for how often the data is updated

Examples

Keyword added

                    {
  "supplierIdentifier": "acme-123",
  "modified": "2024-12-16T00:00:00Z",
  "status": "Published",
  "title": "Advance Passenger Information",
  "description": "Travel data and personal data given to airlines by passenger. API covers  both inbound and outbound air passengers. API includes the passenger’s full name, nationality, date of birth, gender and travel document number, type and country of issue.The data does not include those arriving by sea or rail routes, by private aircraft or via the Common Travel Area (CTA).",
  "type": "Data Set",
  "theme": [
    "Transport and infrastructure",
    "Population and society"
  ],
  "keyword": [
    "Air travel",
    "Passport",
    "Airports",
    "leaving UK",
    "entering UK",
    "New keyword here!"
  ],
  "contactPoint": [
    {
      "name": "Rob Nichols",
      "email": "robert.nichols@digital.cabinet-office.gov.uk",
      "role": "contact"
    }
  ],
  "license": "Microsoft.OpenApi.Any.OpenApiObject",
  "publisher": "academy-for-social-justice",
  "securityClassification": "OFFICIAL",
  "accessRights": "OPEN",
  "distribution": [
    {
      "title": "CSV download",
      "description": "Complete dataset provided as a downloadable file",
      "accessService": [
        "8d085327-21b6-4d8b-9705-88faad231d23"
      ],
      "downloadURL": "http://example.com/path/to/file.csv",
      "format": "CSV file",
      "mediaType": [
        "text/csv"
      ]
    },
    {
      "title": "Rest API",
      "accessURL": "http://example.com/api/",
      "description": "A fully queryable REST API with JSON and XML output",
      "format": "API"
    },
    {
      "title": "Web Page",
      "description": "A web page that provides the data, links to downloads, or documentation.",
      "downloadURL": "http://example.com/path/to/page",
      "format": "Web page",
      "mediaType": [
        "text/html"
      ]
    }
  ]
};

Contact point name changed

                    {
  "supplierIdentifier": "acme-123",
  "modified": "2024-12-16T00:00:00Z",
  "status": "Published",
  "title": "Advance Passenger Information",
  "description": "Travel data and personal data given to airlines by passenger. API covers  both inbound and outbound air passengers. API includes the passenger’s full name, nationality, date of birth, gender and travel document number, type and country of issue.The data does not include those arriving by sea or rail routes, by private aircraft or via the Common Travel Area (CTA).",
  "type": "Data Set",
  "theme": [
    "Transport and infrastructure",
    "Population and society"
  ],
  "keyword": [
    "Air travel",
    "Passport",
    "Airports",
    "leaving UK",
    "entering UK"
  ],
  "contactPoint": [
    {
      "name": "Tom Redfern",
      "email": "tom.redfern@digital.cabinet-office.gov.uk",
      "role": "contact"
    }
  ],
  "license": "Microsoft.OpenApi.Any.OpenApiObject",
  "publisher": "academy-for-social-justice",
  "securityClassification": "OFFICIAL",
  "accessRights": "OPEN",
  "distribution": [
    {
      "title": "CSV download",
      "description": "Complete dataset provided as a downloadable file",
      "accessService": [
        "8d085327-21b6-4d8b-9705-88faad231d23"
      ],
      "downloadURL": "http://example.com/path/to/file.csv",
      "format": "CSV file",
      "mediaType": [
        "text/csv"
      ]
    },
    {
      "title": "Rest API",
      "accessURL": "http://example.com/api/",
      "description": "A fully queryable REST API with JSON and XML output",
      "format": "API"
    },
    {
      "title": "Web Page",
      "description": "A web page that provides the data, links to downloads, or documentation.",
      "downloadURL": "http://example.com/path/to/page",
      "format": "Web page",
      "mediaType": [
        "text/html"
      ]
    }
  ]
};

400

A 400 Bad Request response status is returned for validation or other business errors.

application/json

object

code
string

A system specific code for the global error raised

errors
array of objects

An array of the specific error details

message
string

Summary description of the nature of the error

Example

Validation problems with Dataset metadata.

                    {
  "message": "Validation failures",
  "code": "DM00012",
  "errors": [
    {
      "type": "Fatal",
      "detail": "The attribute 'summary' is too long. It should be less than 250 characters",
      "location": "/summary"
    },
    {
      "type": "Fatal",
      "detail": "The distribution byteSize of '1Mb' is not an integer",
      "location": "/distribution/byteSize"
    }
  ]
};

404

Resource does not exist.

application/json

object

code
string

A system specific code for the global error raised

errors
array of objects

An array of the specific error details

message
string

Summary description of the nature of the error

Example

Dataset not found

                    {
  "message": "Dataset with identifier  does not exist.",
  "code": "DM00010",
  "errors": []
};