Ed-Fi Unifying Data Model Versioning

Owned by Ian Christopher (Deactivated)
Last updated: Feb 25, 2021
3 min read

 The Ed-Fi Unifying Data Model (UDM) is divided into product editions that align to Ed-Fi Suites. Within each edition, the model is versioned using semantic versioning.

Table of Contents

Key Terminology

The terms "Ed-Fi Data Standard" and and "Ed-Fi Unifying Data Model" are equivalent. "Data Standard" is most often used in external contexts, and Unifying Data Model is most often used in technical contexts, as it clarifies that the data standard is a logical model for education data.

This document uses the term "Unifying Data Model", but those uses are interchangeable with the term "Data Standard."

UDM Product Editions and Suite Alignment

Periodically the Ed-Fi Unifying Data Model (UDM) will undergo a set of major revisions. Rather than model these as major version changes, these new releases are regarded as a new, separate UDM product, or product edition. These editions typically reflect sweeping changes to the Ed-Fi model. The new model should be regarded as a separate product from the last edition.

By convention, the edition name will have suffix that aligns it with the Ed-Fi Suite, as in "Ed-Fi Unifying Data Model 3." This edition would be aligned to and part of Ed-Fi Suite 3

Use of Semantic Versioning within UDM Product Editions

Within product editions, Ed-Fi UDM is versioned using semantic versioning ("semver"); see https://semver.org/ for more information.

Since the UDM is a conceptual model only, and strict semantic versioning requires the concepts of “incompatibility” and “backward compatible” some additional guidelines must be present to determine if a conceptual change qualifies in one of these categories. To determine this, the following guideline is used to define "incompatible":

If a change to the UDM would break a currently defined, downstream API (built according to an existing Ed-Fi API standard, and that represents a binding to the UDM), as exercised by a API client writing data to the API (i.e. via a POST or a PUT).

Likewise, “backwards compatible” uses this guideline:

If a change to the UDM would introduce changes but not break a currently defined, downstream API (built according to an existing Ed-Fi API standard, and that represents a binding to the UDM), as exercised by a API client writing data to the API (i.e. via a POST or a PUT).

Note that API reads/GETs are not factored into these guidelines, though in most cases reads would share the same breaking/non-breaking state as writes. Possible downstream database schema changes or changes to other bindings outside of a published Ed-Fi API are not considered.

Versioning Prior to Unifying Data Model 3 v3.4.0

This versioning system began with Unifying Data Model 3, v3.4.0. 

Prior to 3.4.0, versioning attempted to capture concepts of "major change", "minor change" and "patch number" within the 3 version numbers.  https://github.com/Ed-Fi-Alliance/Ed-Fi-Standard

GitHub Conventions

The GitHub repo "Ed-Fi Unifying Data Model" uses a combination of folder structure and repo tags, all based on version numbers. Ed-Fi has found over time that this structure is more familiar to and usable by many consumers, which is why it differs from how many software product repos are organized. 

The structure has a master branch that looks like this:

root

folder UDM edition name

folder major.minor

Full patch and pre-release version information are captured within repo TAGs on the master branch.

Ed-Fi API Standards Versioning

Ed-Fi APIs use semantic versioning (semver)

Metadata/header information for specific API standards will (if applicable) refer to Ed-Fi Unifying Data Model or Suite compatibility so that users can consider this information as they evaluate the specifications. However, there is no attempt to align version numbers or product names with Ed-Fi Suites - e.g. “Assessment Outcomes API v3.0.1” is not to be regarded as necessarily aligned with "Ed-Fi Suite 3" or "Unifying Data Model 3."