Skip to main content
Ed-Fi.orgDocsCommunityAcademy

Ed-Fi Data Standard Extension Framework Best Practices

What is an Ed-Fi Data Standard extension?​

An Ed-Fi Data Standard extension adds data that the core Ed-Fi Data Standard does not include, for a specific implementation. An extension can add new entities, add elements to existing entities, or subclass existing entities, following the rules of the Extension Framework described on this page. Extensions are built with the MetaEd IDE. The Ed-Fi API then generates API resources for the new entities, and includes extended elements in an _ext object in the JSON. These appear under a namespace that shows who defined them — for example with URL fragment /<extension namespace>/<new entity> instead of /ed-fi/<new entity>.

Why extensions exist​

The core Data Standard cannot meet every requirement of every implementation in a given time frame. The most common case is mandated compliance reporting: a state education agency often has to collect state-specific indicators that are not used elsewhere in K–12. Extensions also let the community try out proposed changes to the model in practice before they are added to the standard.

Local and community extensions​

  • Local extensions are defined by one organization, usually a state education agency, for its own requirements. See Examples of State Extensions.
  • Community extensions are defined and shared by a group of organizations for a need they have in common, so others can adopt them. A community extension can later move into the core Data Standard. For example, the Educator Preparation Data Model (Community Edition) was held as a community extension until its entities moved into Data Standard 6.

How extensions affect interoperability​

Extensions trade some standardization for the ability to meet local requirements. Used carefully, they let an agency be interoperable where it can and customize only where it must. Used incorrectly, they fragment the ecosystem. Each extension is extra work for the vendors that send the data, and an integration built for one agency's extensions may not work for other agencies. See API Extensions for how extensions look to API clients.

When not to create an extension​

Do not create an extension when:

  • The Data Standard already has the element. Extensions should not duplicate elements that are already in the data model.
  • The business process can change instead. During data mapping, check with the business owners whether their process can align with the standard.
  • The data is an aggregate, such as a count. Collect the underlying student-level records instead.
  • An upcoming Data Standard release covers the gap and waiting is an option.
  • The change is not a supported extension type. See Unsupported Modifications.

Before extending, talk with the Ed-Fi Data Standard team through the Community Hub. The rest of this page covers when to extend, how to extend, and best practices in more detail.

Introduction​

The Ed-Fi Data Standard and related technologies can be extended to add new entities and elements. The set of standard extensions are codified in the Ed-Fi Data Standard Extension Framework, documented herein. This knowledge base article attempts to provide an overview and best practices for the Ed-Fi Data Standard Extension Framework.

This article assumes prerequisite knowledge from the Ed-Fi Academy:

If you have not already completed these courses, we recommend doing so before attempting to digest the information presented in this article.

Overview of the Ed-Fi Data Standard Extension Framework​

Framework Reference Implementation​

An implementation of the Ed-Fi Data Standard Extension Framework is provided via the MetaEd IDE. The Ed-Fi Community has relied heavily on this reference implementation and downstream technology implementations (e.g., the API implementation in the Ed-Fi ODS/API, etc.) to define patterns that have proven stable and are believed to be widely implementable.

The Alliance and the Ed-Fi community welcome other Extension Framework implementations to contribute their tools and knowledge to this effort.

What is the Extension Framework?​

Ed-Fi Data Standard Extension Framework is the new entities, attributes and/or associations Ed-Fi Alliance Community members can include in their local Ed-Fi Technology Suite implementation (as an addition to those already included in the Ed-Fi Data Standard Core Model) according to the guidance provided by the Ed-Fi Alliance.

depiction of the framework

Why are Extensions necessary?​

Extensions serve a pivotal role in the evolution of the Ed-Fi Data Standard, reflecting the Ed-Fi Alliance’s commitment to an adaptive, user-driven framework. By allowing for the organic growth of the standard through real-world use cases, extensions become a dynamic tool for addressing the diverse and evolving needs of the community. Far from being mere stop-gap solutions, extensions embody our proactive approach to expanding standardization and ensuring that the Ed-Fi Data Standard remains an organically growing, responsive entity that accommodates the complexities and nuances of educational data.

Extensions become imperative when the Ed-Fi Data Standard core offering falls short of meeting specific requirements for a given implementation in a given time frame. In such cases, extensions serve as a deliberate and strategic response to bridge the gap between the standard and the unique or specific needs of individual Ed-Fi states and collaboratives.

What type of Extensions are supported?​

The framework allows adding new entities, extending existing entities, or subclassing existing entities. Extensions in this category generally have implementation and documentation support in Ed-Fi Technology Suite such as the Ed-Fi ODS / API. See the Supported Extensions Tech Docs page for more specific guidelines.

Extensions not in the Extension Framework are not allowed. The documentation attempts to enumerate the most common of those. The Extension Framework evolves over time, so there are some community input mechanisms in place to help the community explore new models that may be candidates for support. See Unsupported Modifications for commonly encountered scenarios.

When to Extend the Ed-Fi Data Standard​

Deciding whether an extension is necessary involves a thoughtful assessment of your specific data requirements within the Ed-Fi Data Standard framework. Follow the steps below to make this determination:

  1. Start your data mapping. Begin by conducting a comprehensive data mapping exercise. Evaluate your organization's data needs against the existing Ed-Fi Data Standard. Identify any gaps or instances where the standard does not adequately address your specific use cases. As you identify gaps, work with the appropriate business owners to see if their process can be modified to align with the standard instead of defaulting to the other way around.
  2. Engage the Ed-Fi Data Standard team. If your data mapping reveals a gap in the Ed-Fi Data Standard that cannot be resolved through modification of an internal business process, don't hesitate to engage with the Ed-Fi Data Standard team. Seek their expertise and guidance to understand whether your identified gaps are intentional design choices or if they represent areas that may benefit from extension.
  3. Collaborate with the Ed-Fi Community. Leverage the collaborative nature of the Ed-Fi community. Discuss your findings and potential requirements with other stakeholders who may have faced similar challenges. Community insights can provide valuable perspectives on whether an extension is a shared need or a more isolated requirement. This also includes the vendors that are sources of the data to confirm the impact on their integration effort.

How to Extend the Ed-Fi Data Standard​

Implementing an extension involves using the MetaEd Integrated Development Environment (IDE). The MetaEd IDE is a powerful tool designed to simplify the process of creating, managing, and deploying extensions. Here's a high-level overview of the steps involved:

  1. Understand the MetaEd IDE. Start by familiarizing yourself with the MetaEd IDE. This tool serves as the central hub for extension development within the Ed-Fi ecosystem. For an in-depth understanding, refer to the MetaEd Page.
  2. Define and build the extension. See the How To: Extend the Ed-Fi ODS / API - Alternative Education Program Example for step-by-step guide using the Student Transportation extension as an example.
  3. Create an Extension Plugin. See the How To: Create an Extension page.
  4. Deploy an Extension Plugin. See the How To: Deploy an Extension page.

Best Practices​

Below is a list of best practices to consider when working with the Extensions Framework.

  • If possible, avoid extensions. Carefully assess your need to extend the core Ed-Fi Unifying Data Model and justify the assessment result by comparing it with the previous work and conversation of the Ed-Fi Community.
  • Get help with data mapping. The Ed-Fi Data Standard team is here to assist with your data mapping questions and guide you with the extension modeling. You can connect with them by going to the Community Hub
  • Refrain from making unsupported modifications. Do not extend the Ed-Fi Data Model in ways that are not supported. See the Supported Extensions for more specific guidelines.
  • **Be cautious about aggregate data.**The idea of using extensions to hold aggregate data elements comes up often in data mapping exercises. In general, the Ed-Fi Alliance recommends avoiding aggregates in favor of the underlying discrete data used to compute them.
  • Assess the impact and long-term viability of an extension. Consider the potential impact of introducing an extension on your system and data ecosystem (including your vendors). Evaluate whether the extension aligns with your long-term goals and whether it is a sustainable solution for addressing your unique data needs.
  • Evaluate future standard updates. As mentioned earlier, Ed-Fi Data Standard extensions play a key role in ensuring the Ed-Fi Data Standard continues to stay relevant as new data collection sources come online.  Stay informed about upcoming releases and updates to the Ed-Fi Data Standard. Some of your identified gaps may be addressed in future versions. Assess whether waiting for an upcoming release is a viable option for your organization. Also, develop a plan to share your extension with the Ed-Fi Alliance Community members for a larger adoption if you go that route. If you are a state education agency or a regional agency, connect with your community peers to understand if they created an extension for a similar use case and how they have done it.  The Ed-Fi Alliance’s governance workgroups (SEA Working Group and Collaborative Working Group) can facilitate these discussions, you can email them at governance@ed-fi.org.