Descriptor Guidance

Note that the Alliance has significantly modified its advice on descriptors usage going forward. Please see Descriptor Guidance under Ed-Fi Data Standard v4 for details.

This article provides guidance for field work on the usage of Ed-Fi descriptors.

Table of Contents

What is an Ed-Fi descriptor?

Descriptors are the data model elements that hold standardized enumerations — the "code sets" used to categorize data and power reporting and analytics. Examples would be:

The academic subject for a course (e.g., Mathematics, Chemistry, Social Studies).
The grade level a student is enrolled in (e.g., Pre-K, First Grade).
The type of accommodation a student was provided for an assessment (e.g., Scheduling, Extra time).

In the Ed-Fi data model, each element that is populated by a predefined code set is referred to as a "descriptor."

Descriptor Usage Classifications

A common question in the community is when and how to use custom descriptor values, either in addition to or instead of the standard set provided by Ed-Fi specifications. To assist with that answer, the Alliance analyzed field usage to classify descriptors by how often they are customized.

The following classifications are not part of the formal Ed-Fi standards; they are non-normative. They are based on an analysis of community practice by the Alliance and provide some guidance with regards to where agencies and organizations are likely to find more value in staying within the Ed-Fi descriptor value sets.

There are four classifications: Standard, Orthodox, Flexible, and Local.

Classification	Definition	Recommendation	Examples
Standard	There is reason to value standardization highly, because the community is highly standardized (but not perfectly standardized), sometimes due to strong standards like EDFacts reporting. There is reason to believe that with sufficient governance a set of values that can work for a large majority of use cases is possible.	The recommended practice is to stay within the Ed-Fi set if at all possible. It is also likely that the Ed-Fi value set is mandated by an Ed-Fi API standard.	SchoolFoodServiceProgramService
Orthodox	The community is mostly standardized, but exceptions and localization are not infrequent. For these descriptors, Ed-Fi's standards will include a list that mirrors the standardization seen in the community.	The recommended practice is to map to / use all Ed-Fi values within this set when possible, but add local values when and where there is high value to doing so. However, realize that in making additions there may be sacrifices to interoperability. It is possible that the Ed-Fi value set is mandated by an Ed-Fi API standard.	GradeLevel
Flexible	The community is somewhat standardized, or there is one or more common, broadly-adopted vernacular classifications around the concept. Local usage may be completely at odds with the vernacular, and that is to be expected in some cases. For this set, Ed-Fi will generally include a "starter" set of values that mirror the most common vernacular.	The recommended practice is to map to / use Ed-Fi values when applicable, but to also feel free to remove or avoid unnecessary Ed-Fi values.	InternetAccess
Local	The option set values are highly localized in nearly all cases. For this set, Ed-Fi will generally define a "sample" set of values that illustrate possible values, or not provide any Ed-Fi defined values at all.	The recommended practice here is to substitute your own values. There should be no hard or reason to preserve any "default" Ed-Fi-defined values here. Note that many “local” values are classified that way because they are set by the state DOE and districts tend to use the state codes or values.	GradingPeriod

Note that these classifications are somewhat arbitrary and may not apply to all use cases. For example, there may be use cases where GradeLevel, which is generally orthodox, should be local.

To reinforce: these are not "official" categories but are based on observations of usage within the Ed-Fi community. Specific Ed-Fi API standards and certifications will mandate certain value sets for compliance reasons. If a product chooses to conform to that downstream specification, those values will need to align to the Ed-Fi-provided set.

Descriptors by Domain

These links lead to the UDM documentation, which displays the classifications and other related information in the descriptor tables.

Descriptor FAQ

Answers to some of the most common questions from the community around descriptors can be found in the Descriptor FAQ.