Contents

Overview

Data Standard 4 is targeted at deployment starting in the 2023-24 school year. Data Standard v4 (current version 4.0) introduces important updates to 3 domains of the Ed-Fi data model:

• Student Academic Report (Grade & Gradebook area only)
• Assessment
• Finance

These changes come from field feedback and are designed to help drive the community and community innovation forward. There are breaking changes in these domains, so implementers are advised to review the changes. In addition, Data Standard 4 introduces the new concept of managing descriptor mappings as data entities.

Other areas of the model have received minor, non-breaking updates, and API bindings and implementations in those areas should continue to function as before. 

Major Changes

Descriptor Mapping 

In many cases, source systems manage multiple code sets for the same data entity. For example, this is common in SIS systems where the SIS manages both a local value for an element (for example a student event attendance code value) and a state value for that same data entity (the state code value).

Following many years and months of community research and discussion (via the Technical Advisory Group and at the Ed-Fi Technical Congress, among other community venues) Data Standard 4 introduces the concept of sourcing these mappings as data themselves. This capability promises to unlock many valuable use cases for agencies.

For example, it is quite common for a local education agency to need to track both the performance of local programs and the state view of those same programs. Providing access to "canonical" local-to-state descriptor mappings for the school year for code values will be critical in this area.

The element fields for this new entity called DescriptorMapping are as follows:

• string Value
• string Namespace
• string MappedValue
• string  MappedNamespace
• descriptor MappingScope (optional)

A sample mapping would look like this:

{
  "value" : "AlgebraII",
  "namespace" : "uri://grandbendisd.edu/AcademicSubjectDescriptor",
  "mappedValue" : "ADVMATH",
  "mappedNamespace" : "uri://somestate.edu/AcademicSubjectDescriptor",
  "modelEntities" : [
	 { 
       "modelEntityDescriptor": "uri://ed-fi.org/ModelEntity#Staff" 
     }
  ]
}

This sample captures a mapping of code values for AcademicSubject from a local value ("AlgebraII") to a state value ("ADVMATH"), and clarifies that the mapping applies only for the Staff entity. If MappingScope is omitted, then the mapping is assumed to be universal for the current data exchange context.

With the new options Data Standard v4.0 introduces in descriptor management and exchange via Descriptor Mapping entity, a guidance needed to be provided for descriptors. Here are Ed-Fi Data Standard team's recommendations on descriptor usage:

• Descriptor code values should generally be the values that are most native to the local data exchange and usage context, to reduce potential loss of fidelity to the local operational use cases. These are often the code values directly as they appear in the source system. 
• If other code values are used, there should be a clear reason why these values are being used instead of local values. The use of non-local values will increase the loss of fidelity to local operational use cases, so it should be clear what value is created and why this other context for the data exists.
• Descriptor namespaces should clearly indicate the organization that governs the value; this is often the education agency for local operational codes, but in some cases sets my be governed by external organizations (vendors, states, etc.).
• It is not recommended that values in the "ed-fi.org" namespace be used.
• When a source system or other systems in a usage context has mapping data that describes descriptor mappings to multiple usage contexts, the client of the data exchange should be provided those mappings.

More details on the issue can be found at the following TechDoc link. 

Student Academic Report Domain Changes - Grade & Gradebook

Major changes to the Student Academic Record Domain were limited to Grade and Gradebook elements of the model.

Add support for current grades 

A common field request was for the Ed-Fi Data Standard to support exchange of grades for the current, non-concluded grading period. Note that this solution involves both a data model change and normative guidance; the latter is captured in Student Academic Record Domain - Best Practices

This change adds two optional elements that allow a SIS to send current grades. In JSON, they appear as follows as part of the /grades API resource.

{
  ...
  "currentGradeIndicator": boolean,
  "currentGradeAsOfDate" : date,
  ...
}

The indicator is used to indicate that this is a current grade (and not a final term grade) and the "as of" date provides a clear indication of how current this is.

Note also that this a non-breaking change for a SIS that is only posting final grades. However, those that decide to post current grades will need to change their logic for posting current grades (to overwrite). There are also possible downstream implications for reporting. 

While these elements are optional, use of them will likely be a requirement for Ed-Fi certification, to reflect the importance of and community demand for this data.

Changes to GradebookEntry and StudentGradebookEntry Key 

The key to Gradebook needed to be changed to remove potential volatility. The new key adopts the strategy of using the source system surrogate key and a namespace, which follows the pattern for Assessment entities. StudentGradebookEntry inherits these changes. In the JSON, the new key elements for GradebookEntry look as follows:

{
  "gradebookEntryIdentifier": "string",
  "namespace": "string"
...
}

The key to StudentGradebookEntry includes this as a key and adds a student reference. In the JSON, the key there is:

{
  "gradebookEntryReference": {
    "gradebookEntryIdentifier": "string",
    "namespace": "string"
  },
  "studentReference": {
    "studentUniqueId": "string"
  }
...
}

Linking Gradebook entities to Sections

In the Ed-Fi model, the Section entity is derived from the concept (common in Student Information Systems) that a section is both a student grouping/scheduling entity (i.e., it has students and staff attached) and a curricular entity (i.e., it is tied to CourseOfferings). Accordingly the entity key is composed of fields from both.

One issue this creates is that Gradebook systems that are separate from the SIS are often unaware of the curricular elements of the Section entity and cannot therefore provide the curricular elements of the Section key (a CourseOffering reference). 

To solve this problem, a second means of connecting a GradebookEntry to a Section is provided: by using the SectionIdentifer. This requires of course that the SectionIdentidier is unique within the data exchange context. If a system has a full reference to a Section, it can and should also supply that. A consuming system should therefore first attempt to use the Section reference (optional) and if that was not supplied, the SectionIdentifier (required).

{ 
  ...
  "sourceSectionIdentifier": "string"
  "sectionReference": {
      "localCourseCode": "string",
      "schoolId": 0,
      "schoolYear": 0,
      "sectionIdentifier": "string",
      "sessionName": "string"
    }
 ...
}

In the JSON binding, the pattern looks as follows, with the sourceSectionIdentifier required and the sectionRefernce optional.

This pattern encourages systems to make the sourceSectionIdentifier sufficiently unique to resolve to a single course in the current school year. Research shows that this is the practice with nearly all SIS systems, and that those who do not do this have a clear path forward to make this change in their Ed-Fi representation.

Gradebook authorization

While not a data model change per se, the model now assumes that the most common pattern for authorizing access to gradebook will be via namespace. Accordingly GradebookEntry is given a field named Namespace in order to allow host API systems to drive authorization in this fashion. This is due in part to the above changes relating to section, and the lack of clarity that all gradebook systems track or roster formal Section or even Education Organization identifiers.

Other authorization patterns are still possible; this is mainly to signal to systems that namespace may be the chosen pattern.

Removal of deprecated LearningObjective from Grade and Gradebook elements

Removal of LearningObjective links into the Gradebook model is the most significant of these. LearningObjective had been previously deprecated in favor of having a single entity – LearningStandard – that was used to manage any references to formal academic standards, regardless of if those were local, state or national in scope.

Assessment Domain Changes

A number of changes were made to the Assessment domain, including breaking changes. The changes to the domain do not represent fundamental rethinking or restructuring of the domain; rather they represent opportunities for implement and alignment with industry practice.

Changes relating to AssessmentPeriod 

Interim benchmark assessments are critical to most education agencies in academic planning and intervention, and these benchmarks are usually given in and marked with a windows or periods - "beginning of year", "middle of year" or "fall", "spring" etc. In previous data model versions, there was only the ability to capture a single period on the Assessment entity, and the StudentAssessment result was assumed be linked to that period via its link to Assessment. This model proved too inflexible in many cases, such as where an assessment was used in multiple periods, or where a student result needed to be attributed to a different period.

The new model allows the capture of multiple AssessmentPeriods on Assessment, and then the attribution of a student result to a period is made explicitly via a field AssessmentPeriod on StudentAssessment.

 "periods": [
      {
        "assessmentPeriodDescriptor": "string",
        "beginDate": "2022-08-16",
        "endDate": "2022-08-16"
      }
    ]

  "period": {
      "assessmentPeriodDescriptor": "string",
      "beginDate": "2022-08-16",
      "endDate": "2022-08-16"
  }

Tracking time spent on assessments

There were a  number of field requests to track time students spent on an assessment, and some fields were added to enable this:

• AssessedMinutes was added to StudentAssessment
• AssessedMinutes was added to StudentObjectiveAssessment (a sub-entity on StudentAssessment)

The latter provides the ability to track amount of time spent on sub-sections or elements of an overall assessment.

Tracking assessment dates and allowing for capture of un-assessed students

Some refinements have been made to date tracking.

• StudentAssessment.AdmistratonDate was changed from required to optional to reflect that there was not always a single unified date for many assessment administrations, and that it would be burdensome to require accounting of all dates. For example, in many cases early literacy benchmarks are performed across multiple sessions, and technology-driven assessments have also led to situations where there is not a single clear date/time for an assessment.
• AdmistratonDate was added to StudentObjectiveAssessment to allow for optional tagging of a particular sub-element of an assessment to a certain date.

Making a date optional on StudentAssessment is also critical to allowing a way to capture untested students - see

Removal of deprecated PerformanceLevelMet boolean

This element had been deprecated in the Data Standard 3.x line. To show which level was met by a student assessment, the model had previously required a re-listing of the PerformanceLevels and the marking of the one met with this boolean value. That was unnecessary and confusing and had been deprecated. The new model removes this element.

Resolve ambiguities in mapping of PerformanceLevels in complex assessments

In very complex assessments with multiple scores in the assessment hierarchy, there was a possibility of ambiguity in how performance levels were linked from assessment metadata to student assessment results. PerformanceLevelIndicatorName was added to the model to make the link explicit. See the attached tickets for details.

ScoreResult changed to an optional collection on StudentObjectiveAssessment 

This change aligns the metadata on the ObjectiveAssessment with the student results capture. Formerly, ScoreResult was required on the student results but optional on the assessment metadata. To bring these into alignment,  ScoreResult is now optional on both ObjectiveAssessment and StudentObjectiveAssessment.

Removal of deprecated elements from Assessment domain

The most significant of these is the removal of links to LearningObjective, which has been deprecated for several releases.

Finance Domain Changes

Data Standard 4 replaces the older Finance domain with changes from ED-FI RFC 18 - FINANCE API - this is a direct swap of domains. The following chart is intended to be a helpful guide to the changes. 

General changes

Significant cleanup of default descriptor values

Work was done to clean up default descriptor values sets, including adding values that were missing and deprecating outliers. This work focused on sets that are often highly localized – see the ticket for details.

Alignment of a number of descriptor sets to EDFacts

EDFacts analysis had revealed a number of opportunities to align default values for entities that are commonly used in state reporting better with EDFacts values. This release included a number of changes in this area.

All Changes

View all: