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	`GET`	`POST`	`PUT`	Notes
`namespace`	yes	yes	yes
`codeValue`	yes	yes	yes	Value preferred to be one or more words rather than a numeric code or random string.
`shortDescription`	yes	yes	yes
`description`	yes if a value was provided in POST / PUT	opt	opt	Longer description that may contain additional normative usage guidance.
`effectiveBeginDate`	yes if a value was provided in POST / PUT	opt	opt	Date for display only, not validation
`effectiveEndDate`	yes if a value was provided in POST / PUT	opt	opt	Date for display only, not validation
`id`	yes	no	yes
`_etag`	opt	no	no	Required when the host implements etags.
`xyzDescriptorId`	opt	no	no	Retained only for backward-compliance with existing ODS/API implementations.
`priorDescriptorId`	opt	no	no	Retained only for backward-compliance with existing ODS/API implementations.
`lastModifiedDateTime`	opt	no	no	Date for display only, not validation

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
`/[abc]Descriptors`	Adds a new Descriptor	Gets all Descriptors for the subtype	Error	Error
`/[abc]Descriptors/{id}`	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.,

uri://ed-fi.org/AcademicSubjectDescriptor#English%20Language%20Arts

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 of codeValues 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 the endDate on an existing Descriptor, or clarify the description, without otherwise modifying the namespace and codeValue.

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.