What's New - Minor Changes

Owned by Ian Christopher
Jun 24, 2017
7 min read

This section describes the relatively minor changes made to the Ed-Fi Data Standard from v2.0 to v2.1, along with the rationale for the changes. Minor changes are likely non-breaking to most field work due to the limited scope of the change or infrequent use of the changed entities or elements. A complete list of every change can be found in the Release Notes section of this documentation.

Minor Changes to the Data Model

Discussed in this section:

Detail on each follows.

Changed Representation of Assessment Family in the Model (DATASTD-926)

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 AssessmentFamily entity duplicated many data fields from the Assessment entity. For example, both had attributes for GradeLevel, AcademicSubject, Category, Version, and several other fields. This duplication introduced ambiguity. If values for the same field name such as AcademicSubject differed between the Assessment and the AssessmentFamily associated with that Assessment, which value would be judged to be correct? Rather than create rules at the Data Standard level for interpretation of such situations (which would have been a new direction, and could easily be missed by those implementing API and other clients), v2.1 instead simplifies the model.

Though AssessmentFamily has been used to group Assessments in field work, there was no identified use of the optional (and redundant) fields in AssessmentFamily and no use cases using these fields were noted during the Request for Comment periods.

The Ed-Fi Data Standard v2.1 changes the model by removing the AssessmentFamily domain entity and introducing an AssessmentFamily field directly on Assessment. Assessments can be associated with each other through use of this new field.

Change Detail

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

  • Removed the AssessmentFamily domain entity from the model. 
  • Replaced the reference to AssessmentFamily in the Assessment domain entity with optional string AssessmentFamily. 
  • Changed Assessment.Namespace to be required (since it was previously required in AssessmentFamily).

Reference

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

Removal of Volatile Fields in Keys of Less Used Entities (OpenStaffPosition and RestraintEvent) (DATASTD-908, DATASTD-978)

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 infrequently used entities OpenStaffPosition and RestraintEvent had volatile keys. Similar to the change on Section, key fields were dropped from these less-used entities in the model in v2.1. In both cases, the entity is expected in field work to have surrogate source system key, and also has an EducationOrganization reference (e.g., an organizational scope); those two attributes should be sufficient to define the identity. 

Change Detail

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

  • StaffClassification, EmploymentStatus, and DatePosted were removed from the OpenStaffPosition key and included as required fields.
  • EventDate was removed from the RestraintEvent key and included as a required field.

Reference

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

Added Date Support to Student Education Organization Association (DATASTD-967)

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

StudentEducationOrganizationAssociation is used to represent cases in which a particular responsibility for a student (e.g., funding, discipline, etc.) has been assigned to a different education organization than the one in which the student is enrolled (enrollment is captured through a StudentSchoolAssociation).

The Ed-Fi Data Standard v2.0 model only permitted representation of a static, “current” representation of such a responsibility relationship as the entity had no dates attached. Adding a BeginDate and EndDate to StudentEducationOrganizationAssociation permits the history of changes in an EducationOrganization's responsibility for a student to be preserved, which was a documented field need. Consistent with other enrollment and assignment records in the model, BeginDate attribute was made part of the key.

Change Detail

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

  • Added BeginDate to StudentEducationOrganizationAssociation. BeginDate is required and part of the key.
  • Added EndDate to StudentEducationOrganizationAssociation as an optional property.

POST to /studentEducationOrganizationAssociations in Data Standard v2.1
{
  "id": "458948e3de8547608024bfaf9ab53533",
  "educationOrganizationReference": {
    "educationOrganizationId": 255901107,
    "link": {
      "rel": "school",
      "href": "/school?schoolId=255901107"
    }
  },
  "studentReference": {
      "studentUniqueId": "605266",
      "link": {
        "rel": "Student",
        "href": "/students?studentUniqueId=605266"
      },
  "responsibilityDescriptor": "Individualized Education Program",
  "beginDate": "2016-11-01",
  "endDate": "2017-03-31",
  "_etag": "635696150777400000"
}

Lines 17 and 18 show the new values. In this example, the student was in an individualized education program from November 1, 2016 through March 31, 2017. As with other BeginDate and EndDate date ranges in the Ed-Fi model, an empty or null EndDate element signifies that the association is still current.

Reference

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

Changes to and Expansion of Staff Credential Model (DATASTD-940)

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

Specific staff credentials are often used as the basis for specific teaching or employment assignments. In the Ed-Fi Data Standard v2.0, credentials were captured as a collection directly on Staff as a common type, which meant that they could not be easily referenced from employment and other associations. To solve this problem in v2.1, Credential is modeled as a core domain entity (rather than as a common type), and optional references to Credentials have been added on StaffEducationOrganizationAssignmentAssociation and StaffEducationOrganizationEmploymentAssociation.

The v2.1 model also expands the Credential entity to capture new attributes found in field work.

Change Detail

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

  • Promoted Credential from common type to domain entity.
  • Added reference to Credential on Staff as optional collection.
  • Added optional reference to Credential on StaffEducationOrganizationAssignmentAssociation and StaffEducationOrganizationEmploymentAssociation.
  • Added Credential to StaffAssociation interchange.

Reference

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

Removal of the LevelDescriptor Entity (DATASTD-1013)

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

In Ed-Fi Data Standard v2.0, the Credential common type (on Staff) included a Level descriptor reference that served the same purpose as – and was essentially a duplicate of – the GradeLevelDescriptor entity. In v2.1, the Credential type (added as a domain entity in v2.1) was changed to use GradeLevelDescriptor. LevelDescriptor was removed from the model.

Change Detail

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

  • Credential type changed to use GradeLevelDescriptor. 
  • LevelDescriptor was removed from the model.

At an API level, this will result in the need to rename the field. Under v2.1, the field changed from name "levelDescriptor" to "gradeLevelDescriptor", as shown below:

Credential Entity with GradeLevel Descriptor Under 2.1
{
  "identifier": "9976732B",
  "stateOfIssueStateAbbreviationType": "NC",
  "type": "Certification",
  "gradeLevelDescriptor": "First grade",
...

Reference

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

Removed StateOrganizationID Field and Broadened Applicability of EducationOrganization Concept (DATASTD-972)

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

In the Ed-Fi Data Standard v2.1, A few changes have been made to reinforce the applicability of the Ed-Fi data model to local education agency use cases.

The initial Ed-Fi model was derived from state-level use cases and therefore required a StateOrganizationId for all EducationOrganizations. In state field work and usage, this field value often confusingly duplicated the concrete subclass keys (e.g., School.SchoolID = School.StateOrganizationId). Further, requiring a StateOrganizationID can make the model more difficult to use in cross-state use cases. Field work also suggests that NCES IDs (a federal identifier) are likely a more efficient option. For all of these reasons, the field EducationOrganization.StateOrganizationId has been dropped from the model in v2.1

Entity definitions were also adjusted to allow for non-state identifiers for EducationOrganizations (e.g., to allow use of NCES IDs).

Change Detail

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

  • Removed attribute StateOrganizationId from EducationOrganization domain entity.
  • Removed the text "by the State Education Agency (SEA)" from the annotation of the EducationOrganizationId field in EducationOrganization and all EducationOrganization subclasses (School, LocalEducationAgency, StateEducationAgency, EducationServiceCenter, and EducationOrganizationNetwork).

Reference

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

Changed Cardinality of References to Sections and Programs referenced from StudentLearningObjective and StudentCompetencyObjectives (DATASTD-1018)

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 model only allows for one Section or Program enrollment to be associated with a StudentLearningObjective or a StudentCompetencyObjective.

Feedback from field work has shown that a student's performance on a learning objective or competency objective may be related to multiple sections in which they are enrolled or multiple programs in which they are participating. 

Change Detail

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

  • Updated the cardinality of the StudentSectionAssociation and StudentProgramAssociation references in the StudentLearningObjectiveSectionOrProgramChoice and the StudentComptencyObjectiveSectionOrProgramChoice to allow collections.

Reference

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

Alignment of Language and Country Enumerations to ISO Standards (DATASTD-928, DATASTD-971)

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

The Ed-Fi Data Standard v2.1 adopts the ISO 639-3 language codes and names for the Language descriptors, and eliminates the optional Language (map) type. Formerly, v2.0 did not provide a comprehensive language enumeration to support cross-sector interoperability use cases. Adoption of the ISO spec is intended to address that functionality.

Likewise, v2.1 formally adopts ISO 3166 (2-letter) codes for country codes and country names. This had been implicit in the sample data supplied with Data Standard v2.0, but as with languages, the specification did not provide a comprehensive enumeration set.

Finally, v2.1 eliminates the optional LanguageMapType. (In Ed-Fi Data Standard v2.0, the LanguageMapType entity contained only three elements, which are of limited value: English, Spanish, and Other). This change is seen as establishing a new pattern in the Data Standard: when an enumeration is based upon and follows an externally governed and referenced enumeration set (e.g., the ISO code/value sets), the Data Standard likely only needs a descriptor and no map type as map types provide no additional value (i.e., they would match the external enumeration set exactly).

Change Detail

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

  • LanguageMapType entity was removed from the model.
  • LangaugeDescriptor definition was changed to formalize the reference the ISO 639-3 language enumeration.
  • The sample Ed-Fi Descriptor file was updated to include the full array of options per ISO 639-3 to support implementations such as the Ed-Fi ODS / API.
  • Updated annotation for Country descriptor and all references to Country descriptor reference ISO 3166 2-letter country code enumeration.

Reference

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