Form Instructions: Descriptor Management
Purpose of this Form
This form is used to add or modify existing descriptors to ensure that descriptors are always in sync in each environment. Note that this request will only update the descriptors contained in the ODS (and thus, the potential descriptors used for publishing). Vendors that interact with the ODS will still have to be informed about the changes so that they can update and/or remap their code. This form is the ONLY method for requesting a change to the ODS descriptors.
School Year and Environments
Fill in this information as the requester. Note that all of these fields are required:
School Year*: Select all school years that this change should be applied to. If historical years are chosen, please explain in the Notes section why these retroactive changes are needed.
Environment - State/District*: Select one option
Environment - Prod/Dev*: Select one option
Request Type*: Add new descriptors OR modify existing descriptors.
After data has landed in the ODS, modifying existing descriptors should only happen rarely and only after an analysis to ensure that the change does not affect data integrity or meaning.
Namespace and Code Value can never be changed.
Description and Short Description may be modified to correct spelling/grammar issues, but should not change the meaning of the descriptor (since the existing data will have been published based on the old meaning).
If the meaning of a descriptor needs to be significantly altered, a new descriptor should be created instead, and appropriate effectivebegindate and effectiveenddate set.
Fields marked with * are required
Descriptors Management
Please attach a CSV (comma-delimited values) file containing all of the descriptors that need to be added/modified.
Descriptors Management CSV -
The file should contain the following column headers (* are required). See the link to a sample file with the column headers pre-populated and an example descriptor row (please remove the example descriptor before submitting)
Field | Required | Description | Max Length |
|---|---|---|---|
descriptor | Yes | The descriptor category (e.g. “AcademicSubjectDescriptors”). This should always be plural and start with a lowercase letter. |
|
namespace | Yes | The full namespace for the descriptor category (e.g. “uri://doe.state.gov/AcademicSubjectDescriptor”). This should usually be in the state-controlled namespace. |
|
codevalue | Yes | Unique descriptor code. Can contain alphanumeric characters and spaces (e.g. “Social Studies”, “001”). Does not need to be intuitive. | 50 characters |
shortdescription | Yes | Brief, human-readable description of the descriptor, for use in dashboards and reports. Can contain alphanumeric characters and punctuation (enclose in double quotes if containing commas). Can be identical to codevalue if desired. | 75 characters |
description | Yes | A longer, more detailed description of the descriptor. Can contain alphanumeric characters and punctuation. Must enclose in double quotes if containing commas (e.g. “Social Studies, civics, history, psychology, and other courses that encompass the study of human society and social relationships”). Can be the same as codevalue/shortdescription if additional detail is not needed. | 1024 characters |
effectivebegindate | No | The date that the descriptor is considered “in use.” This does not inherently drive any functionality, but is useful to note when a new descriptor is added to replace a deprecated one. (e.g. “2025-03-27”) |
|
effectiveenddate | No | The date that the descriptor is considered “no longer in use.” This does not inherently drive any functionality, but is useful to note when a descriptor is deprecated. (e.g. “2025-03-27”) |
|
notes | No | Any specific notes, details, or context about the specific descriptor being added/modified. This will not be added to the ODS, but will be stored in the ticket and the descriptor repository for future reference and troubleshooting. |
|
Note: if there is an external list of descriptors (non-ODS), that will need to be updated as well.