# OS NGD Versioning

## What is OS NGD schema versioning?

Ordnance Survey is implementing schema versioning to OS NGD feature types to allow the easy flow of data updates to each data theme. ​

For example:​

* For the release of a new feature type in OS NGD: This will always be Version 1 (V1). The data never existed in OS NGD before, and this is therefore the first version. <mark style="color:purple;">This will be Feature Type V1</mark>
* For the release of a new schema to an existing feature type in OS NGD:  The feature type already exists in OS NGD, so a new additional version is created which incorporates the updates that have been made.  <mark style="color:purple;">This will lead to Feature Type V2, V3 etc.</mark>

## Type of data releases

**New Schema**​ - The release of a new schema will cause a feature type to have a new version. A new schema is created when additional fields are added or when the addition or removal of attribution has occurred​

**​Data Enhancement**​ - The release of a data enhancement will not cause a feature type to have a new version. A data enhancement is when the existing data quality has been improved, but there are no changes to the fields or attribution specified in the dataset​

​**New Feature**​ - The release of a brand new feature will be known as version 1 of that feature type. A new feature will contain the original schema, and can be adapted by data enhancements​

## What does versioning look like over time?

* As new data updates are made and released, the versioning will continue (V1, V2, V3 etc…)​
* To manage versioning over time there will be a ‘latest’ version and ‘maintenance’ versions
* ​Once a new ‘latest’ version is released, the previous version will become a ‘maintenance’ version : ​<mark style="color:red;">V 1 – maintenance</mark>, <mark style="color:blue;">V 2 – latest​</mark>
* A maintenance version is still available in OS NGD and usable through OS Select+Build​
* There will be no more than three versions available in OS NGD at any one time (one ‘Latest’ and up to two ‘Maintenance’ versions)​ : <mark style="color:red;">V 1 – Maintenance</mark>, <mark style="color:blue;">V 2 – Maintenance</mark>, <mark style="color:purple;">V 3 – Latest​</mark>
* Once three versions have been released, Version 1 will be removed from OS NGD, and will no longer be available through OS Select+Build​

<figure><img src="/files/5vHroopl65ycIK9NXMEQ" alt="Image of a gant chart showing that versions are withdrawn after 2 new versions have been released"><figcaption></figcaption></figure>

## An example with OS NGD Address

Built Address is a feature type found under the Address theme, and in the GB Address collection​

It is an existing feature type which means it has a current Version number. As there hadn’t been any data updates since it was first released to OS NGD, it was released as Version 1​

There have now been updates made to the Built Address schema as some new fields and attributions have been added​

Updates to feature types are released in OS NGD updates (every 6 months – March or September)​

When a new version is available the feature type, in this example we choose Built Address, and it defaults to the newest version available, which is then Version 2​

<figure><img src="/files/LkgSORNclbZuM0dB2g2G" alt="image showing that on OS Select+Build the version of the schema is shown" width="563"><figcaption></figcaption></figure>

### Recipes

When a new version of the feature type is live, you can choose what version you want to download by selecting the feature type and choosing from the dropdown list. In this example we select Built Address and choose version 2​

Version 1 is the Built Address feature type with the original schema containing the original fields and attribution (no new fields or attribution will be in this version)​

Version 2 is the Built Address feature type with the new schema containing the original and new fields and attribution​

You can find out what the new fields and attribution are by navigating to the National Geographic Database Platform on the OS Gitbook site​

<figure><img src="/files/C2k92roG9Gna1WSpRsQJ" alt="Image showing filtering in OS Select+Build and the ability to choose the version you want in the recipe" width="563"><figcaption></figcaption></figure>

### ​Gitbook help​

When a new schema version is released (or close to release), the OS NGD Platform on Gitbook will be updated​

Using the OS NGD Address example; A notification will appear under the applicable Address feature types that are receiving updates and changes in the new version when a release is planned but not yet live​

Under each field that is available within the feature type a new metadata point ‘Data Schema Version’ has been added which says what versions of this feature type has this field in it​

For either new fields or fields receiving new attribution that are not in the original version but are in the new version, the ‘Data Schema Version’ will only specify the new version​

<figure><img src="/files/o7Mwio6ZGIAFgNAp3PpB" alt="Image showing that Data Schema Version is listed in GitBook" width="563"><figcaption></figcaption></figure>

### Versioning in the Recipe Library

When viewing your recipe in the Recipe Library you can tick the box ‘Show schema version’ to view what version of the feature types are included in that recipe​

<figure><img src="/files/6yNedGZzSD4fRg4sfphc" alt="Image showing the &#x27;Show schema version&#x27; tick box" width="563"><figcaption></figcaption></figure>

## ​How will versioning affect you?​

Advanced notice will be given if there are plans to make an update and create a new feature type schema version​

Sample schemas will be made available to ensure customers can understand and support it. Information will be made available via our Gitbook page [OS NGD Documentation ](https://osngd.gitbook.io/osngd/)[Platform](https://osngd.gitbook.io/osngd/) and updated SQL DDL via Github OS NGD Resources​

There is no immediate requirement for customers to adopt a feature type’s new schema version​

12 months or more notice will be given if there are plans to remove a version from OS NGD and therefore make it no longer accessible​

Customers will need to create a new recipe in OS Select+Build to use the new feature type version​

When customers view a recipe in their recipe library there will be an option to view the feature type versions that are included​

***

Links that may be useful:

{% embed url="<https://osngd.gitbook.io/osngd/>" %}

{% embed url="<https://osdatahub.os.uk/>" %}

{% embed url="<https://www.ordnancesurvey.co.uk/business-government/products/os-select-build>" %}

This content has been developed from what was originally a Lightning Talk PowerPoint slide set. These slides are available to PSGA members to view and download from the [PSGA members area of the OS website](https://auth.ordnancesurvey.co.uk/my.policy)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.os.uk/more-than-maps/data-demonstrators/os-ngd-data/os-ngd-versioning.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.