XML Schema - Ed-Fi Descriptors

Ed-Fi Descriptors provide a malleable alternative to structured value lists that are typically expressed via enumerations in XSD. Descriptors are an expanded feature—first introduced in Ed-Fi Data Standard v1.1—that are vital to accommodate the ways in which users of the Ed-Fi Data Standard need to refer to enumerated collections of values.

Descriptors are enumeration vocabularies that are not “fixed” within the XML schema, but are defined in XML files and linked to their source. Descriptors provide implementers with the flexibility to define their own enumerations. Please note that some downstream Ed-Fi XML standards may require the use of particular enumeration sets in order to guarantee interoperability, so the use of the flexibility in this pattern needs to be exercised with caution.

Key features of the Descriptor Pattern are:

Descriptors minimally have a ShortDescription and CodeValue, and may also have a LongDescription. Descriptors allow states and other implementers to continue to use the codes associated with their enumerations.
To support changing enumerations or code sets, Descriptors have an EffectiveBeginDate and EffectiveEndDate that are typically aligned to school years.
To provide support for longitudinal analysis, Descriptors may capture a PriorDescriptor, as appropriate, when codes may change for the same concept or category.
For example, the AttendanceEventCategoryDescriptor allows states and other implementers to define their own attendance codes.
Descriptors are linked to a “namespace” that defines its scope of use. Ideally, a state will publish an enumeration vocabulary or code list at a specific URL. The Namespace element of the Descriptor will contain this URL.

All Descriptors are an extension of the type DescriptorType, shown below:

<xs:complexType name=”DescriptorType” abstract=”true”>
    . . .
	<xs:complexContent>
		<xs:extension base=”ComplexObjectType”>
			<xs:sequence>
				<xs:element name=”CodeValue” type=”CodeValue”>
                . . .
				<xs:element name=”ShortDescription” type=”ShortDescription”>
                . . .
				<xs:element name=”Description” type=”Description” minOccurs=”0”>
                . . .
				<xs:element name=”EffectiveBeginDate” type=”xs:date” minOccurs=”0”>
                . . .
				<xs:element name=”EffectiveEndDate” type=”xs:date” minOccurs=”0”>
                . . .
				<xs:element name=”PriorDescriptor” type=”DescriptorReferenceType” minOccurs=”0”>
                . . .
				<xs:element name=”Namespace” type=”URI”>
                . . .
			</xs:sequence>
		</xs:extension>
	</xs:complexContent>
</xs:complexType>

Consider the example of PerformanceLevel for an Assessment. The performance levels are custom to each assessment (e.g., Met Standard, Commended, College Ready) and cannot be standardized. The PerformanceLevelDescriptor is shown below.

<xs:complexType name=”PerformanceLevelDescriptor”>
    . . .
	<xs:complexContent>
		<xs:extension base=”DescriptorType”>
			<xs:sequence>
				<xs:element name=”PerformanceBaseConversion” type=”PerformanceBaseConversionType” minOccurs=”0”>
                . . .
			</xs:sequence>
		</xs:extension>
	</xs:complexContent>
</xs:complexType>

The entity PerformanceLevelDescriptor holds the CodeValue and Description for each of the performance level enumerations specific to an assessment, as well as other important attributes.

All Descriptor references are an extension of DescriptorReferenceType, shown below.

<xs:complexType name=”DescriptorReferenceType”>
    . . .
	<xs:complexContent>
		<xs:extension base=”ReferenceType”>
			<xs:sequence>
				<xs:element name=”CodeValue” type=”CodeValue”>
                . . .
				<xs:element name=”Namespace” type=”URI” minOccurs=”0”>
                . . .
			</xs:sequence>
		</xs:extension>
	</xs:complexContent>
</xs:complexType>

The entity PerformanceLevelDescriptorReferenceType holds the CodeValue and Namespace for the specified performance level enumeration.

As an example, for a state to define their own graduation codes for GraduationPlanType they would construct an XML file as follows:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<InterchangeDescriptors  xmlns="http://ed-fi.org/0200" xmlns:ann="http://www.ed-fi.org/annotation" xsi:schemaLocation="http://ed-fi.org/0200 Interchange-Descriptors.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<GraduationPlanTypeDescriptor>
		<CodeValue>27</CodeValue>
		<ShortDescription>Minimum</ShortDescription>
		<Description>Minimum High School Program
		   TAC Chapter 74, revised September 1, 2005; including TAC §89.1070(b)(2) for students
		   receiving special education services, revised August 1, 2002.
		   (for students who entered grade 9 in 2007-2008 and thereafter)</Description>
		<EffectiveBeginDate>2007-09-30</EffectiveBeginDate>
		<Namespace>uri://ritter.tea.state.tx.us/GraduationPlanTypeDescriptor</Namespace>
	</GraduationPlanTypeDescriptor>
	<GraduationPlanTypeDescriptor>
		<CodeValue>28</CodeValue>
		<ShortDescription>Recommended</ShortDescription>
		<Description>Recommended High School Program
		   TAC Chapter 74, revised September 1, 2005; including TAC §89.1070(b)(2) for students
		   receiving special education services, revised August 1, 2002.
		   (for students who entered grade 9 in 2007-2008 and thereafter)</Description>
		<EffectiveBeginDate>2007-09-30</EffectiveBeginDate>
		<Namespace>uri://ritter.tea.state.tx.us/GraduationPlanTypeDescriptor</Namespace>
	</GraduationPlanTypeDescriptor>
	<GraduationPlanTypeDescriptor>
		<CodeValue>29</CodeValue>
		<ShortDescription>Distinguished</ShortDescription>
		<Description>Distinguished High School Program
		   TAC Chapter 74, revised September 1, 2005; including TAC §89.1070(b)(2) for students
		   receiving special education services, revised August 1, 2002.
		   (for students who entered grade 9 in 2007-2008 and thereafter)</Description>
		<EffectiveBeginDate>2007-09-30</EffectiveBeginDate>
		<Namespace>uri://ritter.tea.state.tx.us/GraduationPlanTypeDescriptor</Namespace>
	</GraduationPlanTypeDescriptor>	
</InterchangeDescriptors>

Note that for Descriptors, the namespace is required so the source for the Descriptor definition can be uniquely determined. An optional AsOfDate may be supplied to give temporal context to the Descriptor value reference.

Because each value/code for a Descriptor is defined with a namespace, the controlled vocabulary may be defined combining values from more than one namespace. This allows a state to add codes to a federally-defined set or to combine two vocabularies from different contexts. For example, two code lists might be combined for the DisabilityDescriptor, the Individuals with Disabilities Education Act (IDEA) set of disabilities, and the Section 504 set of disabilities, with each set referencing a different namespace.