Overview

Scope & Usage Summary

The Ed-Fi Assessment Outcomes API describes a REST API surface to enable exchange of assessment metadata and student assessment results between disparate and geographically separated systems operated by different organizations.

The API surface is typically implemented as a centralized platform that receives outcome data. The API surface is typically used by client systems that generate assessment outcome data and send that information to the central platform.

Use Cases

The architecture covered by this model of data exchange is intended to serve the following example use cases. Note that these use cases are illustrative, not exhaustive: they outline a few high-value use cases and do not cover all possible use cases.

Exchanging Information About Student Mastery Levels Against Academic Standards

School X has a highly personalized learning process where student mastery is assessed against learning standards on an ongoing basis, sometimes even multiple times during the school day. These mastery levels for each student are recorded in an LMS, assessment, or gradebook system that teachers use to monitor progress to inform lesson planning and individual student "playlist" assignments.

In addition to teacher-delivered instruction and informal assessment, the school relies on external curriculum systems for content delivery. Those systems provide for "exit tickets" that describe the student’s mastery level against a learning standard. The information from the curriculum tools needs to travel to the LMS, assessment, or gradebook system as soon as possible after a student completes a learning unit.

Exchanging Language and Skill Diagnostic Information

A school district uses an online diagnostic system to measure English-language learner capabilities as part of a larger system of identification and support for ELL students. Diagnostic sessions where ELL screening assessments are administered are scheduled ad hoc as students enroll in the district or are otherwise identified. When a student completes a screening assessment, the resulting data needs to travel to a case-management system and to the district SIS system.

Exchanging Benchmark Assessment Results

A provider of interim benchmark assessments (typically given each grading period) needs to transfer results to school districts in machine-readable format. The district wants this information available in its data systems to produce various reports and visualizations.

The school district aggregates this assessment result data alongside other data for the purpose of assessing school-level progress towards yearly goals. Likewise, principals use this data to determine where additional grade level and classroom focus is needed. Assessment results at an item-level or learning standard-level, both in aggregate and at a student level, are used by teachers for planning. The individual student data is also included on quarterly report cards and put into parent portals.

Boundaries & Relationships

Assessment setup prior to test administration is out of scope for the Assessment Outcomes API. Pre-test setup includes common information exchange activities such as creating a roster of students who will be taking the test, planning for accommodations, creating and defining tests, assigning test variants to students, and so forth, all of which are done prior to the use cases relevant to the Assessment Outcomes API.

Similarly, test administration information exchange scenarios are not in scope for the Assessment Outcomes API. These activities, such as real-time monitoring of student progress on a test, adaptive test communication, and similar activities, are done prior to the Assessment Outcomes API use cases.

The API described however can work in conjunction with the Ed-Fi Enrollment API, which provides information on students, including identifiers required for submission of student assessment results via the API.

Standard

Referenced Standards

• RFC 2119. The keywords "MAY", "MUST", "MUST NOT", "OPTIONAL", "RECOMMENDED", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", and "SHOULD NOT" are to be interpreted as described in RFC 2119.
• RFC 8259. Data is exchanged in the JSON Data Interchange Format.
• Ed-Fi Data Standard v3.1.The data model and type definitions align with the Ed-Fi Data Standard, with a few noted exceptions specific to the use cases supported by this API.
• Ed-Fi Assessment Outcomes API for Suite 3 - Descriptor Listings. Client systems MUST support the default Ed-Fi enumeration elements and values in the referenced listings.
• Ed-Fi API Design & Implementation Guidelines v3.1. The design adheres to the normative guidance in the Ed-Fi API Guidelines. Client systems are expected to adhere to applicable guidelines.

Specification Documents

• Ed-Fi Assessment Outcomes API for Suite 3 - Specification (OpenAPI Specification Document). 

Data Model & Definitions

The Ed-Fi Assessment Outcomes API derives from the Assessment domain in the Ed-Fi Unifying Data Model. That domain has the following UML representation:

Note that not all entities in this model are represented as API resources in this API: some entities (e.g., Section or Program) are shown in order to provide a complete picture of all entity references that appear in the API.

Constraints

CON-1.
Clients MUST use the default Ed-Fi enumeration values for all elements in the referenced descriptor listings.

API client systems MUST support the enumeration elements and values specifically listed in Ed-Fi Assessment Outcomes for Suite 3 - Descriptor Listings.

CON-2.
Clients MAY use default enumeration values for select elements.

The list of descriptor elements whose values are allowed to vary include: 

• AssessmentPeriodDescriptor
• PerformanceLevelDescriptor
• AccommodationDescriptor
• AssessmentReportingMethodDescriptor

However, it is RECOMMENDED that default Ed-Fi enumeration values are used where possible.

CON-3.
Clients SHOULD enable configuration of student identifiers.

Calling systems SHOULD allow operators to select which system of student IDs to use when multiple are present. This data point is the Student.StudentUniqueID, which appears in the StudentAssessment.StudentReference.

The K–12 identity ecosystem is still evolving, and there are also "natural" ecosystem barriers to systemwide coordination of unique student identifiers. Likewise, current rostering specifications and systems in place today generally assume multiple student identifiers. Hence, systems participating in data exchange of results tied to a student — such as the Assessment Outcomes API — should assume that multiple student identifiers are possible and be able to communicate contextually in this area.

CON-4.
Clients SHOULD implement robust error handling routines and retry failed transactions.

Though reliability of information systems is constantly improving, systems are occasionally offline. In the K–12 IT ecosystem, as in most IT ecosystems, the ability to capture, display errors, and offer facilities to retry after error conditions are found, have proven to be essential to interoperability. The level of support for these functions will be defined by the use case. Minimally, clients SHOULD have some systems for notification of operators about failed transactions, including the reasons and possible remediation, and some means of automatic or operator-initiated retry for failed transactions.

Operations

OP-1.
Clients calling the API SHOULD be able to perform update and delete operations for API resources previously created.

The intended use of the API surface is to manage data elements that represent an ongoing synchronization between systems of data elements defined by the Ed-Fi Unifying Data Model's Assessment Domain. The API surface is therefore not primarily intended for use cases involving one-time transfers. Rather, the assumption is that corrections or other updates made on the data provider side will flow through the API to downstream systems. 

OP-2.
Clients SHOULD implement robust error handling.

Though reliability of information systems is constantly improving, systems are occasionally offline. In the K–12 IT ecosystem, as in most IT ecosystems, the ability to capture and display or otherwise report errors has proven essential to interoperability. Clients SHOULD have some system for notification to operators about failed transactions, including the apparent cause and possible remediation.

OP-3.
Clients SHOULD support a retry for failed transactions.

The facility to retry an operation after an error condition has occurred is valuable to interoperability. The level of support for retry functions will be defined by the use case, but minimally, the client SHOULD have some means of automatic or operator-initiated retry for failed transactions.

Conformance Tests

• Ed-Fi Assessment Outcomes API for Suite 3 Certification. Conformance tests inclusive of data exchange, normative requirements, and best-practice guidance are covered by the certification tests for this standard. While the tests are typically run in conjunction with a formal product certification, the tests themselves are publicly documented and may be used to test conformance of any system using this standard.

Data Mappings

Many resources in the Assessment Outcomes API have analogous values in other data exchange standards. Mappings are provided below. These mappings are informative and are provided for implementers of this specification to understand and use the resources as intended. Implementations may vary, however, so these mappings are to be considered illustrative and not normative.

Mapping to the Ed-Fi Core Student API (RFC-24)

Reference: /wiki/spaces/GOV/pages/20331015

Mapping to the Ed-Fi Enrollment API (RFC-19)

Reference: Ed-Fi RFC 19 - Enrollment API for Suite 3

Mapping to OneRoster 1.1

Reference: IMS OneRoster® 1.1

Mapping to Clever API v2.1

Reference: Clever API v2.1

Implementations

Usage in the following agencies provided material evidence of efficiency of this standard:

• Boston Public Schools, MA
• INsite Collaborative, Indiana University, IN
• Uncommon Schools, MA, NJ, and NY