What's New - Major Changes

Owned by Ian Christopher
Jun 29, 2017

This section describes and illustrates the most significant changes made to the Ed-Fi Data Standard from v2.0 to v2.1, along with the rationale for changes. A complete list of every change can be found in the Release Notes section of this documentation.

Major Changes to the Data Model

Discussed in this section:

Detail on each follows.

Change Section Natural Keys to be Non-Volatile (DATASTD-891)

Impacts: Ed-Fi UDM Handbook, Ed-Fi ODS / API

Many field implementers complained of volatility in the Section natural key under Data Standard v2.0. Section is a significant entity in the Ed-Fi Unified Data Model (UDM), which flows from the importance of class sections in real schools. Most instructional activities in schools and a large number of student performance indicators (e.g., grades, credits) are tied to sections. The Ed-Fi UDM followed suit, and Section is deeply embedded in Ed-Fi UDM relationships. Changes to the Section key are therefore especially problematic in actual implementations.

In v2.1, the volatile values were removed from the natural keys of the Section entity.

The volatile key fields included LocationReference and ClassPeriodReference. That is, changing the physical location or the time of a class in the real world would impact the key, and in practice this kind of change happens frequently. These fields were therefore removed from the key.

The direction for v2.1 was to introduce a partial key surrogate, SectionIdentifier, into the key. This field is assumed to be the surrogate identifier from a source system of record (e.g., a student information system) and that value is combined with the CourseOffering to provide a more stable key. The value of that field is, in many cases, likely the same value as the section attribute UniqueSectionCode, so the introduction of SectionIdentifier could be seen as renaming of UniqueSectionCode (which is also removed from Section), but it also introduces new requirements on uniqueness of those values. 

SequenceOfCourse was not reported as volatile in field work, but was similarly seen as a weak identifying property and not necessary if there is a source system surrogate. Therefore, it was removed as well.

Change Detail

The following changes were made in v2.1:

  • The Section API specification was changed to alter the natural key on Section, removing the volatile values from the natural key (and thus make them optional, e.g., in the API). 
  • Also in Section, the uniqueSectionCode element was changed to sectionIdentifier, which has the same role as a unique identifier, but can accept a surrogate key supplied by a client system.

The changes to Section will have a significant impact on some client systems, so we'll illustrate it here. An easy way to visualize the change is with a HTTP GET using the ODS / API GetById endpoint. In Ed-Fi Data Standard v2.0, the GET would be formed as in the following (with the required parameters in bold). 

{api route}/sections?schoolId=255901107&classPeriodName=01%20-%20Traditional&classroomIdentificationCode=101&localCourseCode=ELA-01&termDescriptor=Fall%20Semester&schoolYear=2011&uniqueSectionCode=25590110701Trad101ELA0112011&sequenceOfCourse=1

In Ed-Fi Data Standard v2.1, the same call to the Section GetById endpoint is:

{api route}/sections?localCourseCode=ELA-01&termDescriptor=Fall%20Semester&schoolYear=2011&sectionIdentifier=25590110701Trad101ELA0112011 

Note that there are fewer required parameters in v2.1 and uniqueSectionCode has been recast as sectionIdentifier.

The more profound effect is in the behavior of the POST to the API. The POST operation is an upsert, meaning that all natural key values must be present. If the ODS / API finds a match, a resource will be updated. If no match is found, a new resource will be created.

Consider the JSON model for an example POST:

POST to /sections in Data Standard v2.1
  {
    "classPeriodReference": {
      "schoolId": 255901107,
      "name": "01 - Traditional",
      "link": {
        "rel": "ClassPeriod",
        "href": "/classPeriods?schoolId=255901107&name=01+-+Traditional"
      }
    },
    "courseOfferingReference": {
      "localCourseCode": "ELA-01",
      "schoolId": 255901107,
      "schoolYear": 2011,
      "termDescriptor": "Fall Semester",
      "link": {
        "rel": "CourseOffering",
        "href": "/courseOfferings?localCourseCode=ELA-01&schoolId=255901107&schoolYear=2011&termDescriptor=Fall+Semester"
      }
    },
    "locationReference": {
      "schoolId": 255901107,
      "classroomIdentificationCode": "101",
      "link": {
        "rel": "Location",
        "href": "/locations?schoolId=255901107&classroomIdentificationCode=101"
      }
    },
    "schoolReference": {
      "schoolId": 255901107,
      "link": {
        "rel": "School",
        "href": "/schools?schoolId=255901107"
      }
    },
    "sectionIdentifier": "25590110701Trad101ELA0112011",
    "sequenceOfCourse": 1,
    "educationalEnvironmentType": "Classroom",
    "availableCredits": 1,
    "characteristics": [],
    "programs": []
  }

In v2.0 of the Ed-Fi Data Standard, a change to the location of the class (classroomIdentificationCode, line 22) would result in a new Section. In v2.1, we removed that potentially volatile value from the set of natural keys – and so a change to the classroom will not result in a new Section record in v2.1.

Similarly, the values for the course sequence (sequenceOfCourse, line 36) and the reference to the class period (schoolId, line 3 and name, line 4) have been removed from the natural key, so those values can change without creating a new entity.

Reference

View ticket in the Ed-Fi Alliance Tracker / JIRA system (DATASTD-891).

Expansion of and Changes to the Calendar Model (DATASTD-914)

Impacts: Ed-Fi UDM Handbook, Ed-Fi ODS / API, Ed-Fi XSD for Bulk Data Exchange

The Ed-Fi Data Standard v2.0 model did not allow a school to have calendars for different grade levels or groups of students and staff, as CalendarDates identity is defined by a School reference and a date under v2.0. Additionally, the association between the CalendarDate and Session entities and the CalendarDate and GradingPeriod entities created confusion regarding the intended usage of the CalendarDate entity for attendance and scheduling.

In practice, different grades or cohorts of students may have different calendars, but the v2.0 model only allowed for one calendar per school. Adding the Calendar domain entity with an optional collection of grade levels means that different grade levels, programs, and so forth may have unique calendars. By adding a reference to Calendar on Cohort, Cohorts in a school may also have different calendars independent of grade levels. CalendarDates are then no longer directly associated with Schools, but instead with Calendars, which are associated with Schools.

Finally, existing ties between the CalendarDate, Session, and GradingPeriod entities imply that CalendarDate may be used to define a Session or GradingPeriod, whereas the intended use for CalendarDate is to be an operational component upon which attendance and student scheduling is determined. These links were removed to clear up this misconception.

Change Detail

The following changes were made in the v2.1 model:

  • A Calendar domain entity was added, with a key consisting of SchoolReference, CalendarCode, and SchoolYear.
  • Additional properties include a required reference to CalendarTypeDescriptor and a reference to GradeLevelDescriptor as optional collection.
  • An optional reference to Calendar was added on the Cohort domain entity.
  • A reference to Calendar was added on the CalendarDate domain entity as part of the identity.
  • All other references to CalendarDate or references from CalendarDate to other entities were removed with the exception of a reference to CalendarDate from SectionAttendanceTakenEvent and the aforementioned Calendar reference on CalendarDate.

Reference

View ticket in the Ed-Fi Alliance Tracker / JIRA system (DATASTD-914).

Fixes to the Bell Schedule Model (DATASTD-948, DATASTD-993)

Impacts: Ed-Fi UDM Handbook, Ed-Fi ODS / API, Ed-Fi XSD for Bulk Data Exchange

In the Ed-Fi Data Standard v2.0, the Bell Schedule domain had a significant modeling error requiring a fix. Specifically, the BellSchedule entity could only be associated with a single calendar date due to the cardinality (1:1) of the CalendarDate reference. (This was traced back to an error drafting v2.0.) As a result of this error, it was impossible to signify the dates for which a BellSchedule is active without creating a lot of duplicative data.

In addition, certain complex schedules were difficult to model in v2.0 because a Section could only reference a single ClassPeriod entity.

Change Detail

In v2.1, we removed the reference to the CalendarDate domain entity, replacing it with an optional collection of date elements named "Date". The annotation reads, "The dates for which the BellSchedule applies". 

The following snippet illustrates the change in the Ed-Fi Core XSD:

Modified BellSchedule in v2.1 Ed-Fi Core XSD
... 
  <xs:complexType name="BellSchedule">
    <xs:annotation>
      <xs:documentation>This entity represents the schedule of class period meeting times.</xs:documentation>
      <xs:appinfo>
        <ann:TypeGroup>Domain Entity</ann:TypeGroup>
      </xs:appinfo>
    </xs:annotation>
    <xs:complexContent>
      <xs:extension base="ComplexObjectType">
        <xs:sequence>
          <xs:element name="BellScheduleName" type="BellScheduleName">
            <xs:annotation>
              <xs:documentation>Name or title of the BellSchedule.</xs:documentation>
            </xs:annotation>
          </xs:element>
          <xs:element name="GradeLevel" type="GradeLevelDescriptorReferenceType">
            <xs:annotation>
              <xs:documentation>The grade levels the particular BellSchedule applies to.</xs:documentation>
              <xs:appinfo>
                <ann:Descriptor>GradeLevelDescriptor</ann:Descriptor>
              </xs:appinfo>
            </xs:annotation>
          </xs:element>
          <xs:element name="SchoolReference" type="SchoolReferenceType">
            <xs:annotation>
              <xs:documentation>The school for which the BellSchedule is defined.</xs:documentation>
            </xs:annotation>
          </xs:element>
          <xs:element name="MeetingTime" type="MeetingTime" maxOccurs="unbounded">
            <xs:annotation>
              <xs:documentation>The MeetingTimes that compose this BellSchedule.</xs:documentation>
            </xs:annotation>
          </xs:element>
          <xs:element name="Date" type="xs:date" minOccurs="0" maxOccurs="unbounded">
            <xs:annotation>
              <xs:documentation>The dates for which the BellSchedule applies.</xs:documentation>
            </xs:annotation>
          </xs:element>
        </xs:sequence>
      </xs:extension>
    </xs:complexContent>
  <xs:complexType>
...

A typical use of the new Date element is shown in the following XML data file snippet. The Date elements signify that this bell schedule covers the first full week in September.

Modified BellSchedule in v2.1 Ed-Fi Core XSD
... 
<BellSchedule>
    <BellScheduleName>Bell Schedule</BellScheduleName>
    <GradeLevel>
        <CodeValue>Ninth Grade</CodeValue>
        <Namespace>http://www.ed-fi.org/Descriptor/GradeLevelDescriptor.xml</Namespace>
    </GradeLevel>
    <SchoolReference>
        <SchoolIdentity>
            <SchoolId>255901107</SchoolId>
        </SchoolIdentity>
    </SchoolReference>

    ... Additional MeetingTime entities elided ...
    
	<MeetingTime>
        <ClassPeriodReference>
            <ClassPeriodIdentity>
                <SchoolReference>
                    <SchoolIdentity>
                        <SchoolId>255901107</SchoolId>
                    </SchoolIdentity>
                </SchoolReference>
                <ClassPeriodName>Period 6</ClassPeriodName>
            </ClassPeriodIdentity>
        </ClassPeriodReference>
        <StartTime>14:30:00+06:00</StartTime>
        <EndTime>15:20:00+06:00</EndTime>
    </MeetingTime>
    <Date>2016-09-05</Date>
    <Date>2016-09-06</Date>
    <Date>2016-09-07</Date>
    <Date>2016-09-08</Date>
    <Date>2016-09-09</Date>
</BellSchedule>
...

In addition, a second change not illustrated above – the ability to reference multiple ClassPeriods from a Section – was introduced to add flexibility to support block schedules or other more complex class scheduling requirements.

Reference

View tickets in the Ed-Fi Alliance Tracker / JIRA system (DATASTD-948, DATASTD-993).

Removal of GradeLevel from Key of BellSchedule and Change to Cardinality (DATASTD-1054)

Impacts: Ed-Fi UDM Handbook, Ed-Fi ODS / API, Ed-Fi XSD for Bulk Data Exchange

In Ed-Fi Data Standard v2.0, GradeLevel was part of the key to BellSchedule. In field work, this was causing two problems:

  • Systems in Ed-Fi-based data exchanges would create a duplicate bell schedule for each grade level in cases where there was only a single bell schedule.
  • Misrepresentation of the bell schedule by selecting a single grade level to include on the record.

Accordingly, GradeLevel was removed from the key to BellSchedule. Further, since a bell schedule often covers multiple grade levels (frequently a whole school), GradeLevel was changed to an optional array.

To accommodate for the key change, the attribute BellSchedule.Name can be used to identify multiple bell schedules, including those by grade level.

Change Detail

The following changes were made in Ed-Fi Data Standard v2.1:

  • Removed BellSchedule.GradeLevel from part of the identity. 
  • Changed BellSchedule.GradeLevel to optional collection.

Reference

View ticket in the Ed-Fi Alliance Tracker / JIRA system (DATASTD-1054).

Changes to Staff Leave Event and Absence Event Entities (DATASTD-924)

Impacts: Ed-Fi UDM Handbook, Ed-Fi ODS / API, Ed-Fi XSD for Bulk Data Exchange

In Ed-Fi Data Standard v2.0, the LeaveEvent entity could accommodate only one day of absence per LeaveEvent record, meaning that a staff leave event spanning multiple days required a separate record for each day of leave. This is inefficient and can be error-prone: for example, a staff member on hospital, maternity, or other leave would have that leave modeled as a set of individual LeaveEvents. A year-long leave would likely be modeled as hundreds of LeaveEvents.

Additionally, the previous model did not differentiate between a staff absence event (missing all or some of one day of work, generally not pre-arranged) and a staff leave of absence (missing work over a period of time, generally on a pre-arranged basis).

This improvement makes several changes in v2.1:

  • The LeaveEvent entity is renamed to StaffLeave. 
  • The EventDate element is renamed BeginDate and an optional EndDate was added. 
  • The LeaveEventCategory element is renamed to StaffLeaveEventCategory.
  • The LeaveEventReason is renamed to Reason.
  • The HoursOnLeave field is removed. 
  • The StaffAbsenceEvent domain entity has been added to accommodate absences that are not leaves of absence. The identity consists of EventDate, an AbsenceEventCategory Ed-Fi Descriptor reference, and Staff reference. 
  • The AbsenceEventReason string and HoursAbsent decimal have been added as optional properties.

Reference

View ticket in the Ed-Fi Alliance Tracker / JIRA system (DATASTD-924).

Change to RaceType Enumeration Values (DATASTD-929)

Impacts: Ed-Fi UDM Handbook, Ed-Fi ODS / API, Ed-Fi XSD for Bulk Data Exchange

In Ed-Fi Data Standard v2.0, the RaceType enumeration contained a value "American Indian - Alaskan Native", which does not align with the Office of Management and Budget (OMB) race type. The official race type is "American Indian - Alaska Native", per the 1997 OMB standards from which the CEDS and most state and local enumeration sets are derived.

Change Detail

Removed the "n" in "Alaskan" so that the RaceType enumeration value reads "American Indian - Alaska Native".

The following code snippet lists the complete v2.1 RaceType in the Core XSD. Line 10 shows the updated value.

Listing for RaceType Definition in v2.1
...
  <xs:simpleType name="RaceType">
    <xs:annotation>
      <xs:documentation>The enumeration items defining the racial categories which most clearly reflects the individual's recognition of his or her community or with which the individual most identifies.</xs:documentation>
      <xs:appinfo>
        <ann:TypeGroup>Enumeration</ann:TypeGroup>
      </xs:appinfo>
    </xs:annotation>
    <xs:restriction base="xs:token">
      <xs:enumeration value="American Indian - Alaska Native">
        <xs:annotation>
          <xs:documentation></xs:documentation>
        </xs:annotation>
      </xs:enumeration>
      <xs:enumeration value="Asian">
        <xs:annotation>
          <xs:documentation></xs:documentation>
        </xs:annotation>
      </xs:enumeration>
      <xs:enumeration value="Black - African American">
        <xs:annotation>
          <xs:documentation></xs:documentation>
        </xs:annotation>
      </xs:enumeration>
      <xs:enumeration value="Choose Not to Respond">
        <xs:annotation>
          <xs:documentation></xs:documentation>
        </xs:annotation>
      </xs:enumeration>
      <xs:enumeration value="Native Hawaiian - Pacific Islander">
        <xs:annotation>
          <xs:documentation></xs:documentation>
        </xs:annotation>
      </xs:enumeration>
      <xs:enumeration value="Other">
        <xs:annotation>
          <xs:documentation></xs:documentation>
        </xs:annotation>
      </xs:enumeration>
      <xs:enumeration value="White">
        <xs:annotation>
          <xs:documentation></xs:documentation>
        </xs:annotation>
      </xs:enumeration>
    </xs:restriction>
  </xs:simpleType>
...

Reference

View ticket in the Ed-Fi Alliance Tracker / JIRA system (DATASTD-929).

Changed Cardinality of ProgramSponsor (DATASTD-802)

Impacts: Ed-Fi UDM Handbook, Ed-Fi ODS / API, Ed-Fi XSD for Bulk Data Exchange

In the Ed-Fi Data Standard v2.0, a Program (e.g., Title I, IDEA) has a single, optional ProgramSponsor. There are multiple possible sponsor types (e.g., federal, state, local) for programs, and field work established that there are cases where a program has multiple sponsors. The attempt to support combinations of sponsors was seen as a poor option (e.g., “federal”, “federal and state”, “state and local”) due to the poor scalability of such a solution. 

In Data Standard v2.1, the attribute Program.SponsorType is changed to an array. This change will lead to different API and bulk expressions, and so is a change of which API clients and producers of bulk XML should be aware.

Change Detail

The following changes were made in Ed-Fi Data Standard v2.1:

  • Changed Program.ProgramSponsor to a collection. 

Reference

View ticket in the Ed-Fi Alliance Tracker / JIRA system (DATASTD-802).

External School Reference on CourseTranscript Broadened to EducationOrganization Reference (DATASTD-797)

Impacts: Ed-Fi UDM Handbook, Ed-Fi ODS / API, Ed-Fi XSD for Bulk Data Exchange

In the Ed-Fi Data Standard v2.0, the CourseTranscript entity allowed a reference to a School. In v2.1, this optional reference on CourseTranscript to School was changed to a reference to the broader abstract class EducationOrganization with an External context, as in practice course transcripts may reference a school, school district, or other entity (e.g., university, external provider). A reference to a school was seen as overly restrictive.

Change Detail

The following changes were made in v2.1:

  • Added optional reference to an education organization named ExternalEducationOrganization on CourseTranscript. 
  • Removed optional School reference from CourseTranscript.

Reference

View ticket in the Ed-Fi Alliance Tracker / JIRA system (DATASTD-797).