This document provides guidance for field work on the usage of Ed-Fi descriptors.
What is an Ed-Fi descriptor?
Categorizations of data is critical in data management and usage. These Descriptors are the Ed-Fi data model elements that hold standardized enumerations - the "code sets" are used to categorize records and data for real world-entities:data and power reporting and analytics.
- the academic subject for a coursecourse
- the grade level a student in enrolled in
- the type of accommodation a student was provided for an assessment
In Ed-Fi, each element that is populated by pre-defined code set is referred to as a "descriptor." Such categorizations are critical in data analysis and usage, and often mandated in compliance reporting.
Which descriptors are most important for my organization to pay attention to?
There are over 160 descriptors in the core Ed-Fi data model and many more in domains currently under development and not yet part of 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 will depend on the APIs your work is making use of.
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) | Assessment Outcomes API | Finance API |
|---|---|---|
Why do Ed-Fi
...
descriptor values have a URL in them?
go through format and namespaceIf you look at a descriptor in a Ed-Fi defined data packet, you will see it has this format:
Do I have to use Ed-Fi-defined values?
The answer to this question is "no" but there may be reasons to try to stay within the Ed-Fi-defined set.Firstwhy 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 anyone can do anything they like with those resources, including manipulating descriptor optionscan be used however desired. Plus, the Ed-Fi Alliance and its community have endorsed the notion that there is no set of code values (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 set sets will be localized.
However, just because variation will always 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 vocabularysets 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.
...
| Category | Definition | Examples |
|---|---|---|
| Standard | There is reason to value standardization highly, because there is great (but not perfect!) standardization within the community. There is reason to believe that with sufficient governance a "good enough for most use cases" set of values is possible. The recommended practice is to stay within this set if at all possible. It is very likely that the value set is mandated by a standard or certification. | GradeLevel |
| Modified | The community is mostly standardized, but exceptions and localization are not infrequent. For these descriptors, Ed-Fi will define 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, but realizing that in so doing there may be sacrifices to interoperability. | AcademicSubject |
| Base | The community is somewhat standardized, or there are 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 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 not use avoid unnecessary Ed-Fi values. | |
| CustomCustomize | 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 defiend defined values at all. The recommended practice here is to add your own values. There should be no hard or reason to preserve any "default" Ed-Fi-defined values here. | GradingPeriod |
...