This document provides guidance for field work on the usage of Ed-Fi descriptors.
Table of Contents
| Table of Contents | ||||
|---|---|---|---|---|
|
...
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."
...
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.
...
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?
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]
...
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 try to stay within these values.
For startersclarity, 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.
...
First, as we noted above, any Ed-Fi descriptor set can be modified in implementation work.
However, in its standards and certification, the Ed-Fi Alliance does issue make specific requirements for usage of values in its standards and certificationsdescriptor values. In order to be judged to be compliant with one of those specification, a product may be required to show that it can adopt use a particular sets, . That set is generally (but not necessarily) ones a set 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 adding to or modifying a particular descriptor set. Should I do that?
The following categories are not part of the formal Ed-Fi specifications, but 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 categorizations.
...
Note that these categories are somewhat arbitrary and may not apply to all use cases - there may be use cases where GradeLevel should be localized! So just
Just to repeat: these are not "official" categories but are based on observations of usage within the Ed-Fi community. Specific Ed-Fi standards and certifications will mandate certain value sets for compliance reasons (so if a product wants chooses to conform to that specification, those value will be "standard"!).
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
If the value is stored in a database, you will often see this URL there as well (possibly in a separate column). This is the pattern followed:
[namespace]#[descriptor value]
The descriptor 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.
How do I create my own descriptors?
Descriptors are simple to create - you just create the code value you need, and of course we recommend strongly that you define the value as well (we have not mentioned it thus far, but descriptors should have a definition).
However, the important part of creating a new descriptor value is that the value should be placed in your own namespace, and NOT placed in the "ed-fi.org" namespace. For example, if you were at a school district called: Great Oaks School District and needed an Academic Subject value called "Linear Algebra II", your descriptor might look like this:
uri://greatoakssd.edu/AcademicSubjectDescriptor#Linear Algebra II
It is recommended but not required that the namespace you choose include a URL that is under your organizations control and resolves to a web property owned by your organization. This helps those who see this value understand who created that value.