Ed-Fi RFC 11 - Major Changes
Major Changes to the Data Model
Changes classified as major are those believed to be breaking to existing integrations for widely operationalized domains (i.e., domains in use in field work across multiple implementations) of the Ed-Fi model, or changes that represent a new and significant design pattern particularly worthy of consideration by the community.
A noted above, this classification system is a guideline only; users are advised to consult Ed-Fi RFC 11 - All Individual Changes.
Discussed in this section:
New Extensibility Pattern (DATASTD-1125)
Impacts: Ed-Fi ODS / API, Ed-Fi XSD for Bulk Data Exchange
The patterns used to extend implementations based on the Ed-Fi Unifying Data Model have been revised substantially. The principal change is that the v3.0 extensibility model requires namespaces for all extensions to the model.
In v2.0 versions of the Data Standard, extension elements on core entities would be commingled with core elements of the Ed-Fi data model. This resulted in two issues:
- It generated confusion as to which elements were core to the Ed-Fi model and which were extensions. This was a serious issue for API client developers and API implementers looking to leverage standardized data exchanges. The proposed segmentation and namespacing clarifies which elements are core and which are not, and also provides indications of the provenance of extended elements.
- If an API used more than one set of extensions, name collisions from those sets were possible. By introducing namespaces, the risk of name collisions across extensions is eliminated.
Change Detail
- In the REST API binding for the UDM, the standard defines a JSON object (
_ext) to hold extension properties, within which extensions are placed on objects names using a namespace. The namespace string is intended to be "light" and not necessarily a URI/IRI or to be deferencable. - The XML/XSD binding impacts have not been proposed yet, but is likely to follow a similar pattern.
{
"studentUniqueId": "397589871",
"firstName": "John",
"lastSurname": "Ortiz",
"tribalAffiliation": "Pascua Yaqui"
}
{
"studentUniqueId": "397589871",
"firstName" : "John",
"lastSurname:" "Ortiz",
“_ext” : {
“SomeState” : {
“tribalAffiliation” : “Pascua Yaqui”
}
}
}
Listing 1. Comparison of data standard extensibility in REST API resource bindings
Reference
View ticket in the Ed-Fi Alliance Tracker / JIRA system (DATASTD-1125).
Removal of Types (DATASTD-1088)
Impacts: Ed-Fi UDM Handbook, Ed-Fi ODS / API, Ed-Fi XSD for Bulk Data Exchange
Data Standard v3.0 changes how standardized enumeration sets (i.e., controlled vocabularies) are supported in the data model.
The entity class of types (e.g., RaceType, AcademicSubjectType) is removed from the UDM, and with it the presence of two different classes of enumeration. Where in v2.0 there were both Ed-Fi Descriptors and types, in v3.0b there are only Descriptors (e.g., RaceDescriptor, AcademicSubjectDescriptor).
The presence of two different "enumeration set" classes in the model was poorly understood and led to substantial variation in practice with downstream applications (via the API and XML bindings). In practice, any controlled vocabulary was seen by field implementers as possibly mutable, particularly in state education agency use cases where specific vocabularies are often mandated. The mappings of Ed-Fi Descriptors to types also caused confusion, as these often forced implementations of APIs and bulk exchanges to map local values to a type value. Frequently, no semantically accurate mapping was possible. Nor did such mapping exercises have clear value in many use cases.
These changes do not mean that conformance of data exchanges to specified vocabularies is not not important; indeed, such conformance is often fundamental to interoperability. But such conformance is best described as a property of a downstream specification, and not as a property of the Unified Data Model.
Change Detail
- "Type"-class of entities removed from the data model, and replaced with Ed-Fi Descriptors.
- Mappings from Descriptors to types are removed
- Instead of type sets, standardized enumeration sets provided as part of the Ed-Fi Data Standard will be surfaced as Descriptor sets in the
ed-fi.orgnamespace. It is possible for the Ed-Fi Data Standard to endorse an externally governed enumeration set (e.g., ISO country or language codes). If so, the appropriate namespace may be employed.
The Alliance also envisions that API and bulk implementations (including those provided by the Alliance and its community via Ed-Fi ODS / API releases) will provide mappings between different Descriptor sets, allowing for support of multiple "operational contexts" (contexts in which controlled vocabularies are different for the same underlying concept), and allowing for explicit declaration of operational context.
Reference
View ticket in the Ed-Fi Alliance Tracker / JIRA system (DATASTD-1088).
Relocation of Evaluation-based Student Attributes to StudentEducationOrganizationAssociation (DATASTD-1082, DATASTD-1086, DATASTD-1119)
Impacts: Ed-Fi UDM Handbook, Ed-Fi ODS / API, Ed-Fi XSD for Bulk Data Exchange
Several properties that we associate with a Student — such as SchoolFoodServicesEligibility or LimitedEnglishProficiency — are typically determined via evaluation processes in school districts. These characteristics therefore demonstrate limited volatility, meaning they can change. In field work, we have seen cases where data "thrashing" occurs when the evaluation process outcomes for the same student differ by LEA. In these cases, the student has sometimes withdrawn from one LEA (de-enrolled) but the LEA still has certain data management rights over the student (e.g., for accurate compliance reporting). In cases like this, each of the two student information systems managing the student record seeks to provide its value, and hence the value "thrashes."
Change Detail
- This change relocates SchoolFoodServicesEligibility, LimitedEnglishProficiency and Disability student properties to the StudentEducationOrganizationAssociation entity. This location is logical given that those properties are attributes typically assigned by an LEA. This solves that thrashing problem, and does so in a manner consistent with the logical relationships of the real-world entities.
- EconomicDisadvantaged to become an StudentCharacteristic
- ProgramParticipation moved from Student onto StudentEdOrgAssociation
- StudentIndicator and StudentCharacteristic moved to StudentEdOrgAssociation
Reference
View ticket in the Ed-Fi Alliance Tracker / JIRA system (DATASTD-1082, DATASTD-1086, DATASTD-1119).
Rename StudentEducationOrganizationAssociation to StudentEducationOrganizationResponsibilityAssociation (DATASTD-1086)
Impacts: Ed-Fi UDM Handbook, Ed-Fi ODS / API, Ed-Fi XSD for Bulk Data Exchange
Under v2.0, StudentEducationOrganizationAssociation was used to capture cases in which a secondary education organization had some kind of responsibility (e.g., funding or discipline) for a student enrolled in another, primary education organization. This entity was poorly named, as the association is not generic in nature but rather has a clear, directed purpose (it defines responsibility). Further, the entity name risked confusion as an enrollment record, which is not necessarily what it is (e.g., consider cases where enrollment is in one LEA, but financial responsibility elsewhere).
Change Detail
The existing StudentEducationOrganizationAssociation was renamed to StudentEducationOrganizationResponsibilityAssociation. That entity captures instances where a second LEA may have some responsibility for a student enrolled at the first EdOrg (e.g., funding or discipline).
Reference
View ticket in the Ed-Fi Alliance Tracker / JIRA system (DATASTD-1086).
Decoupling Meeting Time from Class Period (DATASTD-851)
Impacts: Ed-Fi UDM Handbook, Ed-Fi ODS / API, Ed-Fi XSD for Bulk Data Exchange
The MeetingTime model under v2.0 included a ClassPeriod reference, which prevented the entity from being used to model non-class period meeting times. The MeetingTime entity was also referenced on Intervention, which erroneously tied that entity to class schedules, when intervention meeting times frequently occur off of bell schedule time.
Change Detail
In the 3.0 model, MeetingTime drops the ClassPeriod reference and the BellSchedule.MeetingTime collection becomes a collection of BellSchedule.ClassPeriod. To complete the BellSchedule model, ClassPeriod is given a MeetingTime collection. This allows the BellSchedule model from v2.0 to continue to function, and fixes the MeetingTime abstraction.
Reference
View ticket in the Ed-Fi Alliance Tracker / JIRA system (DATASTD-851).
Addressing Volatility of GradingPeriod Key (DATASTD-1090)
Impacts: Ed-Fi UDM Handbook, Ed-Fi ODS / API, Ed-Fi XSD for Bulk Data Exchange
The GradingPeriod key under 2.0 contained a date (StartDate). Dates have generally proven in field work to be volatile (subject to change and entry error), and in fact recent weather-related events (e.g., hurricanes in Texas and Florida that led to school closures, often for a week or longer) demonstrated several cases of LEAs altering grading period scheduling. Since GradingPeriod cascades extensively in the model, a new key was proposed to address this volatility.
Change Detail
GradingPeriod key removes BeginDate and acquires PeriodSequence and SchoolYear.
This proposed change essentially continues work from Data Standard v2.1, which removed volatility in composite key fields.
Reference
View ticket in the Ed-Fi Alliance Tracker / JIRA system (DATASTD-1090).
Introduction of Period Entity and Pattern to Capture Entity History (DATASTD-1085, DATASTD-1092)
Impacts: Ed-Fi UDM Handbook, Ed-Fi ODS / API, Ed-Fi XSD for Bulk Data Exchange
Over time, the ability of the model to capture multi-year data has grown in importance in the community. Implementers have sought to leverage the standard to exchange historical data, and have also extended the model to make the data "multi-year" aware. This work has been difficult. Since identity in UDM bindings such as the ODS / API is driven by natural keys, dates are often needed to distinguish repeated events and to capture history (e.g., StudentSchoolEnrollments, where BeginDate is part of the key and allows implementations to capture a history of re-enrollment).
While forcing data providers to supply dates may work in areas where dates are strongly governed (e.g., enrollment), in other situations where dates are not strongly governed (e.g., a student's surname is changed) this practice may force on data providers a requirement that cannot be fulfilled (e.g., the data provider system may not record dates for the name change event).
Change Detail
Data Standard v3.0 proposes a pattern for capturing history via a Period entity, employed as an optional collection. This model allows for entities to capture and retain dates reflecting periods in which the data was valid.
"addresses": [
{
"addressTypeDescriptor": "Home",
"stateAbbreviationDescriptor": "TX",
"streetNumberName": "89 South Milton St",
"city": "Grand Bend",
"postalCode": "78834",
"periods": [
{
"beginDate": "2017-08-12",
"endDate": "2017-11-20"
},
{
"beginDate": "2018-02-01",
"endDate": "2017-06-06"
}
]
}
Listing 2. Example of Period entity to capture entity history
The principal concern with the pattern is that in places where multiple clients write/exchange the same entity, it seems possible that a client without the historical context could overwrite the data in the Period entity.
Reference
View ticket in the Ed-Fi Alliance Tracker / JIRA system (DATASTD-1085 , DATASTD-1092).
Change Section Natural Keys to be Non-Volatile (DATASTD-891)
Impacts: Ed-Fi UDM Handbook, Ed-Fi ODS / API, Ed-Fi XSD for Bulk Data Exchange
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.
Due to the issues caused, 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 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:
- 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
uniqueSectionCodeelement was changed tosectionIdentifier, 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 the latest release, the same call to the Section GetById endpoint is:
{api route}/sections?localCourseCode=ELA-01&termDescriptor=Fall%20Semester&schoolYear=2011§ionIdentifier=25590110701Trad101ELA0112011
Note that there are fewer required parameters 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:
{
"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. 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.
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 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
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:
... <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" minOccurs="0" maxOccurs="unbounded"> <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="ClassPeriodReference" type="ClassPeriodReferenceType" maxOccurs="unbounded"> <xs:annotation> <xs:documentation>The class periods 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:element name="AlternateDayName" type="AlternateDayName" minOccurs="0"> <xs:annotation> <xs:documentation>An alternate name for the day (e.g., Red, Blue).</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.
...
<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 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 and 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:
- 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:
- 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).
Changes to Race Values (DATASTD-929, DATASTD-1088)
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
With the removal of enumerations in v3.0b, the RaceType enumeration changed to a Descriptor named Race. Further, the default Ed-Fi Descriptor values for Race have a noteworthy change: The "n" in "Alaskan" was removed, so that the Race value reads "American Indian - Alaska Native".
The proposed Race values in v3.0b are:
- American Indian - Alaska Native
- Asian
- Black - African American
- Choose Not to Respond
- Native Hawaiian - Pacific Islander
- Other
- White
Reference
View tickets in the Ed-Fi Alliance Tracker / JIRA system (DATASTD-929, DATASTD-1088).
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.
To address this, 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:
- 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. 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:
- 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).
Addition of a New Staff Education Organization Contact Association (DATASTD-946)
Impacts: Ed-Fi UDM Handbook, Ed-Fi ODS / API, Ed-Fi XSD for Bulk Data Exchange
This change delivers on two unmet needs in the Ed-Fi Data Standard v2.0: it resolves a technical limitation and also expands the staff domain model to address new use cases.
On the first need, in Ed-Fi Data Standard v2.0, e-mail addresses for staff members were modeled with the ElectronicMail entity directly attached to the Staff entity. While the abstract UDM and XSD allow multiple e-mail addresses, in implementations the ElectronicMail.Type field becomes the obvious choice for determining identity (e.g., an e-mail address can be entered into a system in error). However, that model allows at most one of each type of e-mail address to be stored for a Staff. This causes problems when staff members are associated with more than one school or district, which often results in multiple valid "work" addresses.
On the second need, modeling the ElectronicMail entity directly on Staff entity leaves unclear which e-mail address is associated with which education organization. That causes a logical ambiguity, but also causes practical problems when the data is used as a basis for roster or login IDs at an education organization. Further, field work has shown that there is also a parallel need to identify contacts for specific roles (often externally) within an organization, as in "Help Desk Contact" or "Civil Rights Data Coordinator".
This change enables contact information such as e-mail address to be specified on a per-education-organization basis. Note that the ElectronicMail entity will remain on the Staff entity as well.
Change Detail
This change adds a new StaffEducationOrganizationContactAssociation entity to the Ed-Fi Handbook, the Ed-Fi UDM, and core data artifacts. This new association connects a staff person to an education organization and stores contact information specific to that relationship, allowing staff members to have e-mail addresses associated with a particular school, district, or other education organization.
For completeness (and consistency with other parts of the Ed-Fi model), the new association will use the existing StaffReferenceType, which contains the required association data, e-mail, and other association-specific information such as telephone and address information.
A few characteristics worth noting:
- The model uses the ElectronicMailAddress element (and not the ElectronicMail entity) because the association contains the context normally provided by the e-mail type information.
- ContactType is required. It maps to a ContactType Descriptor, and uses a default value of "Other".
The following snippet illustrates the model expressed in the Ed-Fi Core XSD:
A typical use of the StaffEducationOrganizationContactAssociation would look like the following XML data file snippet:
... <xs:complexType name="StaffEducationOrganizationContactAssociation"> <xs:annotation> <xs:documentation>This association provides the contact information of the staff associated with the education organization.</xs:documentation> <xs:appinfo> <ann:TypeGroup>Association</ann:TypeGroup> </xs:appinfo> </xs:annotation> <xs:complexContent> <xs:extension base="ComplexObjectType"> <xs:sequence> <xs:element name="StaffReference" type="StaffReferenceType"> <xs:annotation> <xs:documentation>The Staff assigned to the EducationOrganization.</xs:documentation> </xs:annotation> </xs:element> <xs:element name="EducationOrganizationReference" type="EducationOrganizationReferenceType"> <xs:annotation> <xs:documentation>The EducationalOrganization to which the Staff member provides services.</xs:documentation> </xs:annotation> </xs:element> <xs:element name="Address" type="Address" minOccurs="0"> <xs:annotation> <xs:documentation>The optional address for the contact associated with the EducationOrganization.</xs:documentation> </xs:annotation> </xs:element> <xs:element name="ContactTitle" type="ContactTitle"> <xs:annotation> <xs:documentation>The title of the contact in the context of the EducationOrganization.</xs:documentation> </xs:annotation> </xs:element> <xs:element name="ContactType" type="ContactTypeDescriptorReferenceType" minOccurs="0"> <xs:annotation> <xs:documentation>Indicates the type for the contact information.</xs:documentation> <xs:appinfo> <ann:Descriptor>ContactTypeDescriptor</ann:Descriptor> </xs:appinfo> </xs:annotation> </xs:element> <xs:element name="ElectronicMailAddress" type="ElectronicMailAddress"> <xs:annotation> <xs:documentation>The email for the contact associated with the EducationOrganization.</xs:documentation> </xs:annotation> </xs:element> <xs:element name="Telephone" type="Telephone" minOccurs="0" maxOccurs="unbounded"> <xs:annotation> <xs:documentation>The optional telephone for the contact associated with the EducationOrganization.</xs:documentation> </xs:annotation> </xs:element> </xs:sequence> </xs:extension> </xs:complexContent> </xs:complexType> ...
... <StaffEducationOrganizationContactAssociation> <StaffReference> <StaffIdentity> <StaffUniqueId>307308</StaffUniqueId> </StaffIdentity> <StaffLookup> <StaffUniqueId>307308</StaffUniqueId> </StaffLookup> </StaffReference> <EducationOrganizationReference> <EducationOrganizationIdentity> <EducationOrganizationIdentifier>255901044</EducationOrganizationIdentifier> </EducationOrganizationIdentity> </EducationOrganizationReference> <Address> <StreetNumberName>1234 Education Ave.</StreetNumberName> <BuildingSiteNumber>Building 3</BuildingSiteNumber> <City>Austin</City> <StateAbbreviation>TX</StateAbbreviation> <PostalCode>78701</PostalCode> <AddressType>Physical</AddressType> </Address> <ContactTitle>Guidance Counselor</ContactTitle> <ContactType> <CodeValue>Other</CodeValue> <Namespace>http://www.ed-fi.org/Descriptor/ContactType.xml</Namespace> </ContactType> <ElectronicMailAddress>james.mctestman@example.com</ElectronicMailAddress> <Telephone> <TelephoneNumber>512-555-1212</TelephoneNumber> <TelephoneNumberType>Work</TelephoneNumberType> </Telephone> </StaffEducationOrganizationContactAssociation> ...
Reference
View ticket in the Ed-Fi Alliance Tracker / JIRA system (DATASTD-946).