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

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*

opt

opt

Longer description that may contain additional normative usage guidance.

effectiveBeginDate

yes*

opt

opt

Date for display only, not validation

effectiveEndDate

yes*

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

* 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

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.,

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.