Controlled vocabularies are common in data modeling and provide a useful way of classifying data elements. These "code sets" are often distributed and managed by state education agencies or local education agencies, and some technology providers have developed highly elaborate sets also in wide use. As such, these classifications often carry deep semantics that are important to those who use the data.
...
- codeValue: this is the actual enumeration value, and is often the value persisted in a database (but it isn't required to be that). It is preferred that this be one or more words rather then a numeric code or random string.
- namespace: this provides a scope for the value, and refers to the organization who defines the values; best practice is to use a URI-format
- description: the full definition for the value
- shortDescription: a shorter version of the description, if needed. This is sometimes used to populate a drop-down lists in user-facing interfaces.
- effectiveBeginDate: this is the date that the descriptor was first available
- effectiveEndDate: this is the date that the descriptor value is retired, if a value has been retired, the client must look for a new value that looks appropriate or communicate with the hosting agency/organization for guidance
Descriptor References
...
In transit, when submitted or retrieved as part of an Ed-Fi API resource transaction, only the codeValue and the namespace are returned. A Descriptor looks like this in the API JSON
...
In this API (which is defined in ED-FI RFC 15 - ASSESSMENT OUTCOMES API), there are no requirements as to what enumeration sets are required. However, in the certification for this API, only certain enumerations are permitted to be tech-provider-supplied and others must be Ed-Fi-governed values: see the /wiki/spaces/EDFICERT/pages/23695117 for an example.. There are currently three major versions of the Data Standard available so look at these locations for examples:
- Ed-Fi Assessment Outcomes API for Suite 3 Certification - Ed-Fi Certification - Ed-Fi TechDocs (atlassian.net)
- Ed-Fi Assessment Outcomes API for Data Standard v4 Certification - Ed-Fi Certification - Ed-Fi TechDocs (atlassian.net)
- Ed-Fi Assessment Outcomes API for Data Standard v5 Certification - Ed-Fi Certification - Ed-Fi TechDocs (atlassian.net)
This requirement to handle both tech-provider-supplied and Ed-Fi-governed values applies only to products seeking Ed-Fi Certification. You can implement the specification without this guidance, but a product that does so will not be eligible for Ed-Fi Certification.
...