Skip to end of metadata
Go to start of metadata

This section describes the principles that guide the data standard governance choices made for the Ed-Fi Unifying Data Model (UDM).

Decisions, Decisions

The Ed-Fi UDM affects all aspects of Ed-Fi technology, from the concrete data standards to the supporting technology that align with the data standards. This means that although the Ed-Fi UDM is abstract, all changes, additions, and improvements have an impact on all the concrete technology pieces maintained by the Alliance and by the Ed-Fi Community.


Changes to the data model are influenced by a number of sources:

  • The Ed-Fi Community
  • The Ed-Fi Special Interest Groups
  • Data Standard RFC Period Comments
  • Field Implementation Reports and Artifacts
  • Bug Reports (e.g., in Ed-Fi Tracker)
  • Common Education Data Standards (CEDS) and other standards related to K–12 education

These influences combine to define each subsequent version of the Ed-Fi UDM.

Making Changes

All changes to the data model have some impact and certain kinds of changes are easier than others. This section defines key points on how the Alliance thinks about changes to the Ed-Fi UDM. 


Corrections made to fix obvious flaws are (relatively) straightforward.

  • Corrections to annotations, definitions, or other non-technical artifacts with no impact to implementations are usually approved. For example, a spelling error in a entity annotation or API definition generally will be made at the earliest opportunity.
  • Corrections and naming inconsistencies in field names are also usually approved. Since these are often breaking changes to implementations, we usually wait for a major release or for a point when other breaking changes are also being released.
  • Modeling errors are occasionally found, or weaknesses become apparent over time. If the error or weakness is in a domain not widely in use (operationalized), the change is usually made in the subsequent minor release. If the error would cause substantial ecosystem impacts, it may be held for a major release.


Additions to the Ed-Fi UDM can often be added to implementations without affecting interoperability – but major additions also mean additional maintenance and documentation overhead, so they aren't made lightly.

  • Adding entire domains or major entities to the Ed-Fi UDM generally require a strong pull from the Ed-Fi Community or a significant technology development in the education data field.
  • Adding domains or major entities also generally happens in conjunction with field work such as proof-of-concept implementations, or deconstruction of technology submitted to the Ed-Fi Exchange.
  • Adding elements to an existing entity requires a lower burden of proof, but still requires documentation of specific use cases from field work.
  • The Alliance periodically reviews how field work is extending concrete implementations. In cases where field work has extended the standard in the same way, the Alliance will work with the community to propose and add Ed-Fi UDM with elements to support those extensions natively. This practice helps reduce ecosystem fragmentation and evolve the scope of K–12 interoperability.
  • Adding required additional elements is often a breaking change – so the Alliance generally waits until a major release to do so. Optional fields may be introduced in an interim release if it appears it can be done without introducing major difficulty for current exchanges.
  • With every release, the Alliance reviews the then-current version of CEDS (primarily the entities and elements in the K–12 domain, but the entire model is scanned). This generates elements proposed for addition. Other data standards relevant to use cases supported by Ed-Fi are also considered and reviewed in a similar fashion.


Deletions can be problematic for implementers, so we tread carefully here. However, judiciously applied, deletions can keep the standard simple and bloat-free.

  • Every update cycle, the model is scanned for elements that appear to be unused in field work and they are flagged for removal.
  • Where possible, elements are deprecated before removal. This provides the community a transition period and also allows for implementers to alert the Alliance about the need met by the entity.
  • Where applicable, mappings or options for handling deleted or deprecated elements are provided. 

Improvements & Fine Tuning

Changes that tweak, modify, or otherwise refactor the Ed-Fi UDM fall into this category – and most of these wind up being a battle between inertia (which is easy to support) and improvement (which takes work, but is nevertheless worth doing).

  • The Alliance looks at all changes, even easy ones, and considers the impact on existing filed work. 
  • Relatively minor changes (e.g., simple re-naming) or easily handled migrations (e.g., changes from an integer to a decimal), are generally approved. Changes with a greater systemic impact (e.g., making a formerly required element optional) go through a more intensive review process.
  • All suggestions are considered, but suggested changes that travel with field experience are preferred. Saying it another way, we enjoy arguments about the abstract data model as much as the next person, but generally don't make changes without some real-world examples to support the argument.


As noted, the Alliance takes input from all sources at every opportunity. Most Ed-Fi Community members have full-time jobs, so we generally reach out only when we have major changes – but those who follow the Alliance's work have many opportunities to provide feedback. Here's our general approach to ensure that we telegraph all changes before they happen:

  • To the extent possible and practical, all Data Standard discussion is documented in the Ed-Fi Tracker DATASTD project. Anyone is invited to participate in that discussion (see the Guidelines).
  • Every change is described in at least one public RFC before it's final. Most Data Standard releases that contain changes to the Ed-Fi UDM will be preceded by several RFCs.
  • Major changes are presented and discussed at the annual Ed-Fi Summit and/or the Ed-Fi Technical Congress, as is applicable in that release cycle.
  • The Data Standard Special Interest Group reviews all domain additions, major entity additions, and major changes.

So, if you care about this stuff, get involved. Comment and share ideas and feedback early and often. 

More Information

To find out more, or to get involved, see The Tao of the Ed-Fi Alliance, particularly the section on Data Standards


UDM Documentation Contents

Explore the Ed-Fi Unified Data Model:

  • No labels