{
    "openapi": "3.0.0",
    "info": {
        "title": "Reference Data Service API",
        "description": "The API specification for the Reference Data Service API being developed by the UK Home Office.\n\nThis API specification uses the [OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md) standard.\n",
        "version": "0.0.1",
        "license": {
            "name": "MIT",
            "url": "https://opensource.org/licenses/MIT"
        }
    },
    "servers": [
        {
            "description": "SwaggerHub API Auto Mocking",
            "url": "https://virtserver.swaggerhub.com/Viable-Data/Reference-Data-Service-API/0.0.1"
        }
    ],
    "tags": [
        {
            "name": "entities",
            "description": "Entities are the collection of reference data tables",
            "externalDocs": {
                "description": "Visit the project Wiki",
                "url": "https://github.com/UKHomeOffice/RefDataBAU/wiki"
            }
        },
        {
            "name": "items",
            "description": "Items are the individual records within the reference data tables"
        }
    ],
    "paths": {
        "/v1/entities": {
            "get": {
                "tags": [
                    "entities"
                ],
                "summary": "Gets the list of entities",
                "operationId": "getEntities",
                "description": "Get the list of entities that are being managed by the Reference Data Services.\n\nThis includes details about the entities' schemas.\n",
                "responses": {
                    "200": {
                        "description": "A list of entities, including their data schemas",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "status": {
                                            "type": "string",
                                            "example": "success"
                                        },
                                        "code": {
                                            "type": "integer",
                                            "example": 200
                                        },
                                        "data": {
                                            "type": "array",
                                            "items": {},
                                            "example": [
                                                {
                                                    "id": 12,
                                                    "entityName": "country",
                                                    "label": "Countries",
                                                    "description": "The list of recognised Countries, with additional information (including ISO codes and continent).",
                                                    "schema": {
                                                        "description": {
                                                            "description": "Countries",
                                                            "schemalastupdated": "10/03/2019",
                                                            "dataversion": 1
                                                        },
                                                        "required": [
                                                            "id",
                                                            "iso31661alpha2",
                                                            "iso31661alpha3",
                                                            "name",
                                                            "continent",
                                                            "iso31661numeric"
                                                        ],
                                                        "properties": {
                                                            "id": {
                                                                "format": "integer",
                                                                "type": "integer",
                                                                "description": {
                                                                    "label": "Identifier",
                                                                    "description": "database unique identity record",
                                                                    "summaryview": "false"
                                                                }
                                                            },
                                                            "iso31661alpha2": {
                                                                "maxLength": 2,
                                                                "format": "character varying",
                                                                "type": "string",
                                                                "description": {
                                                                    "label": "2 digit alpha code",
                                                                    "description": "Country 2 Character alpha code",
                                                                    "summaryview": "true"
                                                                }
                                                            },
                                                            "iso31661alpha3": {
                                                                "maxLength": 3,
                                                                "format": "character varying",
                                                                "type": "string",
                                                                "description": {
                                                                    "label": "3 digit alpha code",
                                                                    "description": "Country 3 Character alpha code",
                                                                    "summaryview": "true"
                                                                }
                                                            },
                                                            "name": {
                                                                "maxLength": 40,
                                                                "format": "character varying",
                                                                "type": "string",
                                                                "description": {
                                                                    "label": "Country name",
                                                                    "description": "Country name",
                                                                    "summaryview": "true"
                                                                }
                                                            },
                                                            "continent": {
                                                                "maxLength": 2,
                                                                "format": "character varying",
                                                                "type": "string",
                                                                "description": {
                                                                    "label": "Continent",
                                                                    "description": "Countinent country is part of",
                                                                    "summaryview": "true"
                                                                }
                                                            },
                                                            "dial": {
                                                                "maxLength": 20,
                                                                "format": "character varying",
                                                                "type": "string",
                                                                "description": {
                                                                    "label": "Phone dial code",
                                                                    "description": "Country dailing prefix",
                                                                    "summaryview": "true"
                                                                }
                                                            },
                                                            "iso31661numeric": {
                                                                "format": "integer",
                                                                "type": "integer",
                                                                "description": {
                                                                    "label": "3 digit numeric code",
                                                                    "description": "Country numeric ISO code",
                                                                    "summaryview": "true"
                                                                }
                                                            },
                                                            "validfrom": {
                                                                "format": "date",
                                                                "type": "string",
                                                                "description": {
                                                                    "label": "Valid from date",
                                                                    "description": "Item valid from date",
                                                                    "summaryview": "false"
                                                                }
                                                            },
                                                            "validto": {
                                                                "format": "date",
                                                                "type": "string",
                                                                "description": {
                                                                    "label": "Valid to date",
                                                                    "description": "Item valid to date",
                                                                    "summaryview": "false"
                                                                }
                                                            }
                                                        }
                                                    },
                                                    "lastupdated": "10/03/2019",
                                                    "dataversion": "1"
                                                },
                                                {
                                                    "id": 13,
                                                    "entityName": "nationality",
                                                    "label": "Nationalities",
                                                    "description": "The list of recognised Nationalities, including some additonal information.",
                                                    "schema": {
                                                        "description": {
                                                            "description": "Nationalities",
                                                            "schemalastupdated": "10/03/2019",
                                                            "dataversion": 1
                                                        },
                                                        "required": [
                                                            "id",
                                                            "nationality",
                                                            "visarequired",
                                                            "evwoptional",
                                                            "diplomaticexception",
                                                            "specialexception"
                                                        ],
                                                        "properties": {
                                                            "id": {
                                                                "format": "integer",
                                                                "type": "integer",
                                                                "description": {
                                                                    "label": "Identifier",
                                                                    "description": "database unique identity record",
                                                                    "summaryview": "false"
                                                                }
                                                            },
                                                            "nationality": {
                                                                "maxLength": 330,
                                                                "format": "character varying",
                                                                "type": "string",
                                                                "description": {
                                                                    "label": "Identifier",
                                                                    "description": "Nationality names",
                                                                    "summaryview": "true"
                                                                }
                                                            },
                                                            "iso31661alpha3": {
                                                                "maxLength": 3,
                                                                "format": "character varying",
                                                                "type": "string",
                                                                "description": {
                                                                    "label": "3 digit alpha code",
                                                                    "description": "Country 3 Character alpha code",
                                                                    "summaryview": "true"
                                                                }
                                                            },
                                                            "iso31661alpha2": {
                                                                "maxLength": 2,
                                                                "format": "character varying",
                                                                "type": "string",
                                                                "description": {
                                                                    "label": "2 digit alpha code",
                                                                    "description": "Country 2 Character alpha code",
                                                                    "summaryview": "true"
                                                                }
                                                            },
                                                            "visarequired": {
                                                                "format": "boolean",
                                                                "type": "boolean",
                                                                "description": {
                                                                    "label": "Visa required",
                                                                    "description": "Is VISA required to visit UK",
                                                                    "summaryview": "false"
                                                                }
                                                            },
                                                            "evwoptional": {
                                                                "format": "boolean",
                                                                "type": "boolean",
                                                                "description": {
                                                                    "label": "Optional - EVW",
                                                                    "description": "Is Electronic Visa Waver optional to visit UK",
                                                                    "summaryview": "false"
                                                                }
                                                            },
                                                            "diplomaticexception": {
                                                                "format": "boolean",
                                                                "type": "boolean",
                                                                "description": {
                                                                    "label": "Exception - Diplomatic",
                                                                    "description": "Are there diplomatic exceptions for visiting the UK",
                                                                    "summaryview": "false"
                                                                }
                                                            },
                                                            "specialexception": {
                                                                "format": "boolean",
                                                                "type": "boolean",
                                                                "description": {
                                                                    "label": "Exception - Special",
                                                                    "description": "Are there special exceptions for visiting the UK",
                                                                    "summaryview": "false"
                                                                }
                                                            },
                                                            "countryid": {
                                                                "format": "integer",
                                                                "type": "integer",
                                                                "description": {
                                                                    "label": "Linked country id",
                                                                    "description": "Country link to Country dataset",
                                                                    "summaryview": "false",
                                                                    "linkedrecord": "country(id)"
                                                                }
                                                            },
                                                            "validfrom": {
                                                                "format": "date",
                                                                "type": "string",
                                                                "description": {
                                                                    "label": "Valid from date",
                                                                    "description": "Item valid from date",
                                                                    "summaryview": "false"
                                                                }
                                                            },
                                                            "validto": {
                                                                "format": "date",
                                                                "type": "string",
                                                                "description": {
                                                                    "label": "Valid to date",
                                                                    "description": "Item valid to date",
                                                                    "summaryview": "false"
                                                                }
                                                            }
                                                        }
                                                    },
                                                    "lastupdated": "10/03/2019",
                                                    "dataversion": "1"
                                                }
                                            ]
                                        }
                                    }
                                }
                            }
                        },
                        "links": {
                            "getEntityByName": {
                                "operationId": "getEntity",
                                "parameters": {
                                    "name": "$response.body#/data/{n}/tablename"
                                },
                                "description": "The `tablename` value returned in the response can be used as the `name` parameter in `GET /entities/{name}`.\n\nNB. multiple links will be provided, one per Entity (but the OpenAPI 3.0 specification doesn't cover this). The `{n}` is accessing the 0-based indexes of the array elements.\n"
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/bad-request"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "The user is not authorized to perform this request",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/authentication-error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v1/entities/{name}": {
            "get": {
                "tags": [
                    "entities"
                ],
                "summary": "Gets data items for an entity (supports pagination and filters/queries)",
                "operationId": "getItems",
                "description": "Get the data items within a data set (supporting pagination).\n\nSupports query string parameters (optional) to search within the data set. To support flexibility across entity definitions the main query parameters are two arrays: keys, values. These accept comma-separated lists.\nIf the number of keys and values in the request are not equal, the request will be rejected.\n\nSupports single `eq` (equal) filtering, example:\n    - id=eq.3\n    - city=eq.London\n\nSupports multiple `eq` (equal) filtering, example:\n    - firstName=eq.Pedro&lastName=eq.Curado\n    - city=eq.London&postcode=eq.SW13 9RQ\n\nSupports single and multiple `neq` (not equal) filtering, example:\n    - continent=neq.AS&continent=eq.EU \n    - continent=neq.AS&continent=neq.EU\n\nSupports single `in` (in list) filtering, example:\n    - name=in.(Portugal, United Kingdom)\n\nNot supported yet:\n    - currently only un-quoted values are supported this means that using values with commas will not return any values for instance: street=in.(Flat 2, 33 Joy St, London, Flat 9, 20 Sad St, London) \n\n\nDefaults to:\n\n- returning both the schema and the data items (the data items can be omitted by setting `schemaOnly=true` in the query parameters)\n- only returning \u2018active\u2019 data items (include inactive items by setting `includeInactive=true` in the query parameters).\n",
                "parameters": [
                    {
                        "in": "path",
                        "name": "name",
                        "schema": {
                            "type": "string"
                        },
                        "description": "The name of the entity.",
                        "required": true,
                        "example": "country"
                    },
                    {
                        "in": "query",
                        "name": "keys",
                        "schema": {
                            "type": "array",
                            "items": {
                                "type": "string"
                            },
                            "example": [
                                "alliance",
                                "aviation"
                            ]
                        },
                        "description": "The field keys that will be searched on.",
                        "style": "form",
                        "explode": false
                    },
                    {
                        "in": "query",
                        "name": "values",
                        "schema": {
                            "type": "array",
                            "items": {
                                "type": "string"
                            },
                            "example": [
                                "OneWorld",
                                true
                            ]
                        },
                        "description": "The field values that will be searched for.",
                        "style": "form",
                        "explode": false
                    },
                    {
                        "in": "query",
                        "name": "schemaOnly",
                        "schema": {
                            "type": "boolean",
                            "default": false
                        },
                        "description": "Controls whether the response contains only the schema, or the schema and the data items."
                    },
                    {
                        "in": "query",
                        "name": "includeInactive",
                        "schema": {
                            "type": "boolean",
                            "default": false
                        },
                        "description": "Controls whether inactive records should be returned as part of the result set. Defaults to only returning currently active records."
                    },
                    {
                        "in": "query",
                        "name": "offset",
                        "schema": {
                            "type": "integer",
                            "minimum": 0,
                            "default": 0
                        },
                        "description": "The number of items to skip before starting to collect the result set."
                    },
                    {
                        "in": "query",
                        "name": "limit",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "default": 100
                        },
                        "description": "The maximum number of items to return in the result set."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "status": {
                                            "type": "string",
                                            "example": "success"
                                        },
                                        "code": {
                                            "type": "integer",
                                            "example": 200
                                        },
                                        "entityName": {
                                            "type": "string",
                                            "example": "country"
                                        },
                                        "entityLabel": {
                                            "type": "string",
                                            "example": "Countries"
                                        },
                                        "entitySchema": {
                                            "type": "object",
                                            "example": {
                                                "description": {
                                                    "description": "Countries",
                                                    "schemalastupdated": "10/03/2019",
                                                    "dataversion": 1
                                                },
                                                "required": [
                                                    "id",
                                                    "iso31661alpha2",
                                                    "iso31661alpha3",
                                                    "name",
                                                    "continent",
                                                    "iso31661numeric"
                                                ],
                                                "properties": {
                                                    "id": {
                                                        "format": "integer",
                                                        "type": "integer",
                                                        "description": {
                                                            "label": "Identifier",
                                                            "description": "database unique identity record",
                                                            "summaryview": "false"
                                                        }
                                                    },
                                                    "iso31661alpha2": {
                                                        "maxLength": 2,
                                                        "format": "character varying",
                                                        "type": "string",
                                                        "description": {
                                                            "label": "2 digit alpha code",
                                                            "description": "Country 2 Character alpha code",
                                                            "summaryview": "true"
                                                        }
                                                    },
                                                    "iso31661alpha3": {
                                                        "maxLength": 3,
                                                        "format": "character varying",
                                                        "type": "string",
                                                        "description": {
                                                            "label": "3 digit alpha code",
                                                            "description": "Country 3 Character alpha code",
                                                            "summaryview": "true"
                                                        }
                                                    },
                                                    "name": {
                                                        "maxLength": 40,
                                                        "format": "character varying",
                                                        "type": "string",
                                                        "description": {
                                                            "label": "Country name",
                                                            "description": "Country name",
                                                            "summaryview": "true"
                                                        }
                                                    },
                                                    "continent": {
                                                        "maxLength": 2,
                                                        "format": "character varying",
                                                        "type": "string",
                                                        "description": {
                                                            "label": "Continent",
                                                            "description": "Countinent country is part of",
                                                            "summaryview": "true"
                                                        }
                                                    },
                                                    "dial": {
                                                        "maxLength": 20,
                                                        "format": "character varying",
                                                        "type": "string",
                                                        "description": {
                                                            "label": "Phone dial code",
                                                            "description": "Country dailing prefix",
                                                            "summaryview": "true"
                                                        }
                                                    },
                                                    "iso31661numeric": {
                                                        "format": "integer",
                                                        "type": "integer",
                                                        "description": {
                                                            "label": "3 digit numeric code",
                                                            "description": "Country numeric ISO code",
                                                            "summaryview": "true"
                                                        }
                                                    },
                                                    "validfrom": {
                                                        "format": "date",
                                                        "type": "string",
                                                        "description": {
                                                            "label": "Valid from date",
                                                            "description": "Item valid from date",
                                                            "summaryview": "false"
                                                        }
                                                    },
                                                    "validto": {
                                                        "format": "date",
                                                        "type": "string",
                                                        "description": {
                                                            "label": "Valid to date",
                                                            "description": "Item valid to date",
                                                            "summaryview": "false"
                                                        }
                                                    }
                                                }
                                            }
                                        },
                                        "offset": {
                                            "type": "integer",
                                            "example": 78
                                        },
                                        "limit": {
                                            "type": "integer",
                                            "example": 3
                                        },
                                        "data": {
                                            "type": "array",
                                            "items": {},
                                            "example": [
                                                {
                                                    "id": 78,
                                                    "iso31661alpha2": "FJ",
                                                    "iso31661alpha3": "FJI",
                                                    "name": "Fiji",
                                                    "continent": "OC",
                                                    "dial": 679,
                                                    "iso31661numeric": 242,
                                                    "validfrom": null,
                                                    "validto": null
                                                },
                                                {
                                                    "id": 79,
                                                    "iso31661alpha2": "FI",
                                                    "iso31661alpha3": "FIN",
                                                    "name": "Finland",
                                                    "continent": "EU",
                                                    "dial": 358,
                                                    "iso31661numeric": 246,
                                                    "validfrom": null,
                                                    "validto": null
                                                },
                                                {
                                                    "id": 80,
                                                    "iso31661alpha2": "FR",
                                                    "iso31661alpha3": "FRA",
                                                    "name": "France",
                                                    "continent": "EU",
                                                    "dial": 33,
                                                    "iso31661numeric": 250,
                                                    "validfrom": null,
                                                    "validto": null
                                                }
                                            ]
                                        }
                                    }
                                }
                            }
                        },
                        "links": {
                            "next": {
                                "operationId": "getItems",
                                "parameters": {
                                    "entity": "$response.body#/entityName",
                                    "offset": "$response.body#/offset",
                                    "limit": "$response.body#/limit"
                                },
                                "description": "The `entity`, `offset` and `limit` values returned in the response can be used as the parameters in `GET /entities/{entity}?offset={offset+limit}&limit={limit}`.\n"
                            },
                            "previous": {
                                "operationId": "getItems",
                                "parameters": {
                                    "entity": "$response.body#/entityName",
                                    "offset": "$response.body#/offset",
                                    "limit": "$response.body#/limit"
                                },
                                "description": "The `entity`, `offset` and `limit` values returned in the response can be used as the parameters in `GET /entities/{entity}?offset={offset-limit}&limit={limit}`.\n"
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/bad-request"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "The user is not authorized to perform this request",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/authentication-error"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/not-found"
                                }
                            }
                        }
                    }
                }
            },
            "patch": {
                "tags": [
                    "entities"
                ],
                "summary": "Request an update to the schema definition of a entity",
                "operationId": "patchEntity",
                "description": "Request updates to the definition of an existing data set (as a partial update).\n\nA request can only be raised for one property of the entity's schema definition at a time.\n\nIn a future version of the API, the response will include a link to the resulting `request` resource (but this isn't implemented yet).\n",
                "parameters": [
                    {
                        "in": "path",
                        "name": "name",
                        "schema": {
                            "type": "string"
                        },
                        "description": "The name of the entity.",
                        "required": true,
                        "example": "country"
                    },
                    {
                        "in": "query",
                        "name": "field",
                        "schema": {
                            "type": "string",
                            "example": "name"
                        },
                        "required": true,
                        "description": "The field that the change is being requested for."
                    },
                    {
                        "in": "query",
                        "name": "property",
                        "schema": {
                            "type": "string",
                            "example": "dataType"
                        },
                        "required": true,
                        "description": "The property that the change is being requested for."
                    },
                    {
                        "in": "query",
                        "name": "newValue",
                        "schema": {
                            "type": "string",
                            "example": "CHARACTER VARYING(50)"
                        },
                        "required": true,
                        "description": "The new value being requested."
                    }
                ],
                "responses": {
                    "202": {
                        "description": "Accepted",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/request-accepted"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/bad-request"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "The user is not authorized to perform this request",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/authentication-error"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/not-found"
                                }
                            }
                        }
                    }
                }
            },
            "post": {
                "tags": [
                    "entities"
                ],
                "summary": "Adds a new item to the entity",
                "operationId": "addItemToEntity",
                "description": "Request the addition of an item to an existing data set.\n\nA request can only be raised for one item at a time.\n\nIn a future version of the API, the response will include a link to the resulting `request` resource (but this isn't implemented yet).\n",
                "parameters": [
                    {
                        "in": "path",
                        "name": "name",
                        "schema": {
                            "type": "string"
                        },
                        "description": "The name of the entity that the item is to be added to.",
                        "required": true,
                        "example": "country"
                    }
                ],
                "requestBody": {
                    "description": "The data to be used to create the new item.",
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/item"
                            }
                        }
                    }
                },
                "responses": {
                    "202": {
                        "description": "Accepted",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/request-accepted"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/bad-request"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "The user is not authorized to perform this request",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/authentication-error"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/not-found"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v1/entities/{name}/history": {
            "get": {
                "deprecated": true,
                "tags": [
                    "entities"
                ],
                "summary": "Gets the history of changes to the entity",
                "operationId": "getEntityHistory",
                "description": "Describes the history of the entity.\n\nThis feature is yet to be designed and is currently inactive.\n",
                "parameters": [
                    {
                        "in": "path",
                        "name": "name",
                        "schema": {
                            "type": "string"
                        },
                        "description": "The name of the entity.",
                        "required": true,
                        "example": "country"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success"
                    },
                    "400": {
                        "description": "Bad request",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/bad-request"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "The user is not authorized to perform this request",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/authentication-error"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/not-found"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v1/entities/{name}/items/{id}": {
            "get": {
                "tags": [
                    "items"
                ],
                "summary": "Gets a single item",
                "operationId": "getItem",
                "description": "Get the details of a single data item, by ID.\n",
                "parameters": [
                    {
                        "in": "path",
                        "name": "name",
                        "schema": {
                            "type": "string"
                        },
                        "description": "The name of the entity.",
                        "required": true,
                        "example": "country"
                    },
                    {
                        "in": "path",
                        "name": "id",
                        "schema": {
                            "type": "string"
                        },
                        "description": "The name of the entity.",
                        "required": true,
                        "example": 78
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "status": {
                                            "type": "string",
                                            "example": "success"
                                        },
                                        "code": {
                                            "type": "integer",
                                            "example": 200
                                        },
                                        "entityName": {
                                            "type": "string",
                                            "example": "country"
                                        },
                                        "entityLabel": {
                                            "type": "string",
                                            "example": "Countries"
                                        },
                                        "entitySchema": {
                                            "type": "object",
                                            "example": {
                                                "description": {
                                                    "description": "Countries",
                                                    "schemalastupdated": "10/03/2019",
                                                    "dataversion": 1
                                                },
                                                "required": [
                                                    "id",
                                                    "iso31661alpha2",
                                                    "iso31661alpha3",
                                                    "name",
                                                    "continent",
                                                    "iso31661numeric"
                                                ],
                                                "properties": {
                                                    "id": {
                                                        "format": "integer",
                                                        "type": "integer",
                                                        "description": {
                                                            "label": "Identifier",
                                                            "description": "database unique identity record",
                                                            "summaryview": "false"
                                                        }
                                                    },
                                                    "iso31661alpha2": {
                                                        "maxLength": 2,
                                                        "format": "character varying",
                                                        "type": "string",
                                                        "description": {
                                                            "label": "2 digit alpha code",
                                                            "description": "Country 2 Character alpha code",
                                                            "summaryview": "true"
                                                        }
                                                    },
                                                    "iso31661alpha3": {
                                                        "maxLength": 3,
                                                        "format": "character varying",
                                                        "type": "string",
                                                        "description": {
                                                            "label": "3 digit alpha code",
                                                            "description": "Country 3 Character alpha code",
                                                            "summaryview": "true"
                                                        }
                                                    },
                                                    "name": {
                                                        "maxLength": 40,
                                                        "format": "character varying",
                                                        "type": "string",
                                                        "description": {
                                                            "label": "Country name",
                                                            "description": "Country name",
                                                            "summaryview": "true"
                                                        }
                                                    },
                                                    "continent": {
                                                        "maxLength": 2,
                                                        "format": "character varying",
                                                        "type": "string",
                                                        "description": {
                                                            "label": "Continent",
                                                            "description": "Countinent country is part of",
                                                            "summaryview": "true"
                                                        }
                                                    },
                                                    "dial": {
                                                        "maxLength": 20,
                                                        "format": "character varying",
                                                        "type": "string",
                                                        "description": {
                                                            "label": "Phone dial code",
                                                            "description": "Country dailing prefix",
                                                            "summaryview": "true"
                                                        }
                                                    },
                                                    "iso31661numeric": {
                                                        "format": "integer",
                                                        "type": "integer",
                                                        "description": {
                                                            "label": "3 digit numeric code",
                                                            "description": "Country numeric ISO code",
                                                            "summaryview": "true"
                                                        }
                                                    },
                                                    "validfrom": {
                                                        "format": "date",
                                                        "type": "string",
                                                        "description": {
                                                            "label": "Valid from date",
                                                            "description": "Item valid from date",
                                                            "summaryview": "false"
                                                        }
                                                    },
                                                    "validto": {
                                                        "format": "date",
                                                        "type": "string",
                                                        "description": {
                                                            "label": "Valid to date",
                                                            "description": "Item valid to date",
                                                            "summaryview": "false"
                                                        }
                                                    }
                                                }
                                            }
                                        },
                                        "itemid": {
                                            "type": "string",
                                            "example": 78
                                        },
                                        "data": {
                                            "type": "object",
                                            "properties": {},
                                            "example": {
                                                "id": 78,
                                                "iso31661alpha2": "FJ",
                                                "iso31661alpha3": "FJI",
                                                "name": "Fiji",
                                                "continent": "OC",
                                                "dial": 679,
                                                "iso31661numeric": 242,
                                                "validfrom": null,
                                                "validto": null
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/bad-request"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "The user is not authorized to perform this request",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/authentication-error"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/not-found"
                                }
                            }
                        }
                    }
                }
            },
            "patch": {
                "tags": [
                    "items"
                ],
                "summary": "Patch a single data item, by ID",
                "operationId": "patchItem",
                "description": "Request an update to the definition of an existing data item (as a partial update).\n\nA request can only be raised for one field of the item at a time.\n\nIn a future version of the API, the response will include a link to the resulting `request` resource (but this isn't implemented yet).\n",
                "parameters": [
                    {
                        "in": "path",
                        "name": "name",
                        "schema": {
                            "type": "string"
                        },
                        "description": "The name of the entity.",
                        "required": true,
                        "example": "country"
                    },
                    {
                        "in": "path",
                        "name": "id",
                        "schema": {
                            "type": "string"
                        },
                        "description": "The id of the data item to be updated.",
                        "required": true,
                        "example": 23
                    },
                    {
                        "in": "query",
                        "name": "field",
                        "schema": {
                            "type": "string",
                            "example": "name"
                        },
                        "required": true,
                        "description": "The field that the change is being requested for."
                    },
                    {
                        "in": "query",
                        "name": "newValue",
                        "schema": {
                            "type": "string",
                            "example": "Belize"
                        },
                        "required": true,
                        "description": "The new value being requested."
                    }
                ],
                "responses": {
                    "202": {
                        "description": "Accepted",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/request-accepted"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/bad-request"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "The user is not authorized to perform this request",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/authentication-error"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/not-found"
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "security": [
        {
            "oAuthKeycloak": []
        }
    ],
    "components": {
        "securitySchemes": {
            "oAuthKeycloak": {
                "type": "oauth2",
                "flows": {
                    "authorizationCode": {
                        "authorizationUrl": "https://sso-dev.notprod.homeoffice.gov.uk/auth/realms/cop-dev/protocol/openid-connect/auth",
                        "tokenUrl": "https://sso-dev.notprod.homeoffice.gov.uk/auth/realms/cop-dev/protocol/openid-connect/token",
                        "scopes": {}
                    }
                }
            }
        },
        "schemas": {
            "item": {
                "type": "object",
                "properties": {},
                "example": {
                    "id": 78,
                    "iso31661alpha2": "FJ",
                    "iso31661alpha3": "FJI",
                    "name": "Fiji",
                    "continent": "OC",
                    "dial": 679,
                    "iso31661numeric": 242,
                    "validfrom": "10/03/2019",
                    "validto": null
                }
            },
            "request-accepted": {
                "type": "object",
                "properties": {
                    "status": {
                        "type": "string",
                        "example": "success"
                    },
                    "code": {
                        "type": "integer",
                        "example": 202
                    },
                    "type": {
                        "type": "string",
                        "example": "accepted"
                    },
                    "detail": {
                        "type": "string",
                        "example": "The request has been accepted for processing, but the processing has not been completed. The request might or might not eventually be acted upon, as it might be disallowed when processing actually takes place."
                    }
                }
            },
            "bad-request": {
                "type": "object",
                "properties": {
                    "status": {
                        "type": "string",
                        "example": "client error"
                    },
                    "code": {
                        "type": "integer",
                        "example": 400
                    },
                    "type": {
                        "type": "string",
                        "example": "bad request"
                    },
                    "detail": {
                        "type": "string",
                        "example": "The server cannot or will not process the request due to something that is perceived to be a client error"
                    }
                }
            },
            "authentication-error": {
                "type": "object",
                "properties": {
                    "status": {
                        "type": "string",
                        "example": "client error"
                    },
                    "code": {
                        "type": "integer",
                        "example": 401
                    },
                    "type": {
                        "type": "string",
                        "example": "unauthorized"
                    },
                    "detail": {
                        "type": "string",
                        "example": "The user is not authorized to perform this request"
                    }
                }
            },
            "not-found": {
                "type": "object",
                "properties": {
                    "status": {
                        "type": "string",
                        "example": "client error"
                    },
                    "code": {
                        "type": "integer",
                        "example": 404
                    },
                    "type": {
                        "type": "string",
                        "example": "not found"
                    },
                    "detail": {
                        "type": "string",
                        "example": "The origin server did not find a current representation for the target resource or is not willing to disclose that one exists"
                    }
                }
            }
        }
    }
}