Data schema versioning

Through the OS NGD, Ordnance Survey aims to iterate and release data enhancements quicker than ever before. We want to be able to do this without disrupting customers who have adopted data schemas and are heavily reliant on a specification remaining the same for a longer period of time. With this in mind, the OS NGD is able to run multiple data schema versions for a single feature type at any given time.

Data schema version: The specification to which OS delivers an OS NGD feature type. This includes the attributes a feature type contains, what the attributes are called, the data types of the attributes, whether they are nullable, the precision (if applicable), the scale (if applicable), whether there is a code list associated with an attribute, and the max length (if applicable).

When we release a new data schema version in the OS NGD, the changes will be visible on the feature type pages of this documentation platform. As you can see from the image below, each attribute on a feature type page states which data schema version it is present within, with the Version Date attribute in the example below being present in both data schema versions 1.0 and 2.0:

Data schema version information is held against each attribute listed on a feature type page.

Please note that data schema versioning is implemented at a feature type level. Therefore, increments and withdrawals of data schema versions are done at a feature type level and not at an OS NGD wide level.

How has data schema versioning been implemented?

As new enhancements are made to a given feature type in the OS NGD which require the schema to be uplifted (for example, new attributes being added, resulting in a major schema version increment from 1.0 to 2.0), the new data schema version will become available via the OS NGD access services (i.e. OS Select+Build and the OS NGD APIs).

There are two types of version increments that can be applied:

• Minor: A non-breaking change that does not usually impact a customer’s implementation of the data, for example, the addition of an attribute value to a code list.

• Major: A significant breaking change that usually impacts a customer’s implementation of the data, for example, the addition or removal of an attribute.

When a data schema undergoes a minor version increment, the previous version will no longer be available. This is because the change is deemed to be so small that there is little to no work involved in customers migrating to the latest version of the data.

When a data schema undergoes a major version increment, the previous version will become known as being in 'maintenance' and the new data schema version will be known as the ‘latest’. This reflects an understanding of the work required for customers to move to a new version and allows time for this to happen.

Latest: The latest data schema version released for a given feature type.

Maintenance: An older data schema version for a given feature type, but one which is still receiving updates and can be accessed by customers via OS NGD access services.

End Of Life: A retired data schema version for a given feature type which is no longer receiving updates and cannot be ordered by customers via OS NGD access services.

When using the OS NGD access services, you will be able to choose which data schema version you want to use for feature types when ordering or interacting with the data where more than one major version exists. You can choose from data schema versions which are in the 'latest' or 'maintenance' states.

If you choose not to specify a data schema version for a given feature type or if you don't change the selection from its default, then you will always be provided with the latest data schema version for that feature type.

Older data schema versions (i.e. those in a maintenance state) will remain in the OS NGD for a period of time; it's important to note that these maintenance versions will continue to receive updates. Before any data schema version is retired for a given feature type (i.e. when it no longer receives updates and will be removed from the ordering and selection process), customer communications will be distributed, and a notice period will be issued to allow sufficient time for customers to upgrade to a newer version of a data schema.

Code list versioning

Code lists within the OS NGD have only one type of version increment applied: major.

A code list will undergo a major version change when a new code list value is added to it. Values will never be removed from a code list because this would impact temporal filtering within the OS NGD.

When a code list undergoes a major version increment, all feature types that implement the code list will undergo a minor version increment, reflecting the data change that will occur.

Worked example

In the worked example below, we demonstrate how a feature type has new major data schema versions released (v2.0 and then v3.0), while maintaining older data schema versions (v1.0 and then v2.0), before the original data schema version (v1.0) moves into end of life and is retired.

Worked example of how data schema versioning works in the OS NGD.

• In this example, the feature type starts with a single data schema version (v1.0), known as the latest data schema version.

• At a point in the future, data enhancements are made which require the data schema version to be uplifted, so a second major data schema version (v2.0) is released. As there can only be one latest data schema version (v2.0), the original data schema version (v1.0) drops down into maintenance – but it still receives updates and is still accessible to customers via the OS NGD access services.

• Further again into the future, additional new enhancements are made to the feature type, requiring a third major data schema version (v3.0) to be released. Again, as before, there can only be one latest data schema version for a feature type (v3.0), so the second data schema version (v2.0) drops down into maintenance. Two major data schema versions (v1.0 and v2.0) are now in maintenance, but again, both are still receiving updates and are accessible to customers via the OS NGD access services.

• At a future point, and after customer communications have been distributed and a formal notification period has elapsed, it is decided to retire the original data schema version (v1.0). V1.0 moves into the end of life state, where it stops receiving updates and can no longer be accessed by customers via the OS NGD access services. V3.0 remains the latest data schema version and v2.0 remains in maintenance, with both data schema versions receiving updates and being accessible to customers via the OS NGD access services.

Annual Full Supply orders and data schema versioning

If you select an Annual Full Supply frequency for your OS NGD data order in OS Select+Build, we will provide you with the data as it was on 01 January of the current year. This means if a new feature type or a new data schema version of an existing feature type was released after 01 January and you order either of these as part of your Annual Full Supply, you will receive an empty data package for the newly released feature type / new data schema version of an existing feature type. The data for the new feature type / new data schema version of an existing feature type will then be included in your supply on the next 01 January after the release.

For example, the March 2025 OS NGD data enhancements release contained 3 new feature types (Building Access Location, Crowd Sourced Name Point, and Street Light), and 11 new data schema versions (Building v4.0, Building Part v2.1, Land v3.1, Path Link v2.0, Rail v3.1, Road Link v4.0, Road Track Or Path v3.1, Site v2.2, Site Access Location v2.0, Structure v3.1, and Water v3.1). The data for the new feature types and the new data schema versions will not be part of Annual Full Supply orders until 01 January 2026.