Ed-Fi Descriptors
Descriptors in the Ed-Fi Data Standard are a set of mechanisms to support flexible enumerations or code sets. The following table defined the attributes of an Ed-Fi Descriptor:
Table 3. Descriptor Attributes
The GET
, POST
, and PUT
columns indicate if the attribute is required ("yes"), optional ("opt"), or must not have ("no").
Attribute |
|
|
| Notes |
---|---|---|---|---|
| yes | yes | yes | Â |
| yes | yes | yes | Value preferred to be one or more words rather than a numeric code or random string. |
| yes | yes | yes | Â |
| yes* | opt | opt | Longer description that may contain additional normative usage guidance. |
| yes* | opt | opt | Date for display only, not validation |
| yes* | opt | opt | Date for display only, not validation |
| yes | no | yes | Â |
| opt | no | no | Required when the host implements etags. |
| opt | no | no | Retained only for backward-compliance with existing ODS/API implementations. |
| opt | no | no | Retained only for backward-compliance with existing ODS/API implementations. |
| opt | no | no | Date for display only, not validation |
* if a value was provided in POST / PUT
URL Construction and HTTP Verb Usage for Ed-Fi Descriptors
Descriptors are also exposed as Resources of an Ed-Fi API and can be accessed and manipulated as follows:
Table 4. Accessing and Manipulating Descriptors
Resource | POST | GET | PUT | DELETE |
---|---|---|---|---|
| Adds a new Descriptor | Gets all Descriptors for the subtype | Error | Error |
| Error | Gets all attributes for an individual Descriptor | Updates an individual Descriptor | Deletes an individual Descriptor |
Descriptor References
Many Ed-Fi Resources have one or more Descriptor in their lists of attributes. The Descriptor value is a Uniform Resource Indicator (URI). The URI for a Descriptor must be constructed in the following format:
uri://[namespace]/[name of descriptor]#[descriptor value]
For example, to refer to the academicSubject
value in the Ed-Fi namespace ("http://ed-fi.org") with a codeValue of "Chemistry" the reference would be the following URI:
uri://ed-fi.org/AcademicSubjectDescriptor#Chemistry
Values must be sent as-is and must not be URI or otherwise encoded.
For example, a descriptor whose codeValue has spaces must be sent thus:
uri://ed-fi.org/AcademicSubjectDescriptor#English Language Arts
... and must not be sent as, e.g.,
The server API application should parse the namespace
and codeValue
from this URI to perform reference validation, unless reference validation has been deliberately disabled. For example, if the API application does not have "Chemistry" as a codeValue
for academicSubject
, then the server must respond with status code 400 when processing a POST
or PUT
request that contains uri://ed-fi.org/AcademicSubjectDescriptor#Chemistry
.
Ed-Fi Descriptor API
An Ed-Fi API should expose all Descriptors via a REST interface, using the standard REST API Conventions. However, it is recommended that access to the HTTP verbs be carefully controlled:
All API clients should have read-access using
GET
requests, so that they may ascertain the full set of values available in the given implementation.Access to the
POST
verb should be granted only in carefully controlled situations, so that the number ofcodeValues
does not proliferate inappropriately.The community best practice is to avoid modifying or deleting existing Descriptors; however, a
PUT
request may be used to modify theendDate
on an existing Descriptor, or clarify thedescription
, without otherwise modifying thenamespace
andcodeValue
.
The Descriptor API is completely described in an Open API 3 specification document. Note that there are multiple versions, matching with the Resources API versions.