...
| Note |
|---|
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.
Contents
| 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 course (Mathematics, Chemistry, Social Studies, etc.)
- the grade level a student in enrolled in ("Pre-K", "First Grade", etc.)
- the type of accommodation a student was provided for an assessment ("Scheduling", "Extra time", etc.)
In the Ed-Fi data model, each element that is populated by pre-defined code set is referred to as a "descriptor."
Which descriptors are most important for my organization's usage of Ed-Fi?
There are over 160 descriptors in the core Ed-Fi data model and many more in domains under development or proposed for introduction into the core model. Not all of them will be relevant to your organization's use of Ed-Fi. Generally, the descriptors that matter most to your organization initially will be those involved in data exchanges between systems, so which matter will usually first depend on the APIs you are using.
A good first list to pay attention to are the descriptors that are required in an Ed-Fi API certification, as these must be present in a data exchange. By API, those descriptors are:
...
Core Student API
(aka the Student Information Systems API)
...
Why do Ed-Fi descriptor values have a URL in them?
If you look at a descriptor in a Ed-Fi defined data packet in the API, you will see it has this format:
uri://ed-fi.org/AcademicSubjectDescriptor#Mathematics
This is the pattern followed:
uri://[namespace]/[descriptor name]#[descriptor value]
The name of descriptor and the value should be clear, but what is the namespace? The namespace is a string value that tells you who governs or defines the value. In this case, you can see that the value "Mathematics" is defined by "ed-fi.org". In other words, the Ed-Fi Alliance defines a value called "Mathematics." If this was an agency with a different definition of mathematics, there could very well be a different descriptor value that looked like this:
uri://mydistrict.edu/AcademicSubjectDescriptor#Mathematics
This is telling you that this is "mydistrict.edu" definition of "Mathematics" and NOT the definition of the Ed-Fi Alliance.
Do I have to use Ed-Fi-defined values?
The answer to this question is "no" but there may be reasons why you should try to use these values.
For starters, no one is forced to use the Ed-Fi values. The Ed-Fi technologies and specifications are open source and can be used however desired. Plus, the Ed-Fi Alliance and its community have discovered over time and endorsed the notion that there is no set of code values for any concept (for example, for grade level) that is universally applicable (see below for more information on this). By definition, this means that we need to expect that code sets will sometimes be localized.
However, just because variation will exist and just because there is no "universally applicable" set of values for any concept, it does NOT follow that it is not helpful for us to adopt a common sets in some cases, and for the Alliance to encourage - sometimes strongly encourage - community members to adopt common values. When we act in common ways, then we can rely on each other, share resources, and interoperate with each other easier.
Said anther way: there may be pain or loss in mapping local values to Ed-Fi values, but that pain provides benefits in terms of interoperability.
In what ways does Ed-Fi encourage or enforce compliance with particular value sets?
First, as we noted above, any Ed-Fi descriptor set can be modified.
However, the Ed-Fi Alliance does issue requirements for usage of values in its standards and certifications. In order to be judged to be compliant with one of those specification, a product may be required to show that it can adopt particular sets, generally (but not necessarily) ones defined by the Ed-Fi Data Standard.
As an example, you can see that the Assessment Outcomes API v3 requires usage of most Ed-Fi defined values, but makes a few exceptions: Ed-Fi Assessment Outcomes API for Suite 3 Certification#FiAssessmentOutcomesAPIforSuite3Certification-Enumerations
My organization is thinking of modifying a particular descriptor set. Should I do that?
...
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. 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 specifications, but standards; they are non-normative. They are based on an analysis of community practice by the Alliance and provides 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 4 categorizationsfour classifications: Standard, Orthodox, Flexible, and Local.
| CategoryClassification | 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 "good enough for most use cases" set of values 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 veryalso likely that the Ed-Fi value set is mandated by a standard or certificationan Ed-Fi API standard. | GradeLevelSchoolFoodServiceProgramService |
| Orthodox | The community is mostly standardized, but exceptions and localization are not infrequent. For these descriptors, Ed-Fi's standards will define 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 so doingmaking additions there may be sacrifices to interoperability. AcademicSubjectIt 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 define 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 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 a possible values, or not provide any Ed-Fi defined values at all. | The recommended practice here is to addsubstitute 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 |
How do I create my own descriptors?
All code sets depend on a context; said another way, there is no such thing as a code set that will work for all contexts. While we may think of some categorizations as being universal – such as grade levels - there are always and will always be variations, somewhere. This is part of the natural variation of the education ecosystem.
However, because there are always possible variation does not mean that there is not value to encouraging (perhaps strongly in some cases) usage and community governance of some sets of values. if we all agree to use the same set of values for grade level, that can hep us a great deal to share resources. There may be loss in converting our values to those values, but the benefits may be worth it.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 value 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 into in the descriptor tables.
- Alternative and Supplemental Services
- Assessment
- Bell Schedule
- Discipline
- Education Organization
- Enrollment
- Finance
- Graduation
- Intervention
- School Calendar
- Staff
- Student Academic Record
- Student Attendance
- Student Cohort
- Student Identification and Demographics
- Survey
- Teaching and Learning
Descriptor FAQ
...
Answers to some of the most common questions from the community around descriptors can be found in the Descriptor FAQ.