This section provides an overview of the new features in the v3.1 of the Ed-Fi ODS / API. A comprehensive list of all changes is in the Release Notes section. 

The changes include:

Detail about each change follows.

Improvements and Bug Fixes - Version 3.1.1

This release is a maintenance release and includes enhancements and bug fixes contributed by the Ed-Fi Alliance and implementers. A few important enhancements include:  

• Adjustment to Assessment claimsets
• Enhancement to the version endpoint to include data standard and extension version numbers
• A migration utility for migrating to v3.1.1
• A new  resource dependency graph endpoint
• Support for an upcoming cloud ODS v3.x release

Improvements - Version 3.1

Alignment With the Ed-Fi Unifying Data Model v3.1

Every generation of Ed-Fi technology is aligned with the Ed-Fi Unifying Data Model. The ODS / API v3.1 implements the Unifying Data Model v3.1, which contains a limited set of breaking changes to the Data Standard v3.0 model in the Assessment domain and a few non-breaking changes in other core student information system domains.

• The changes in the latest UDM have an impact to the surface of the ODS / API. See the Ed-Fi Data Handbook v3.1 for more details.
• API documentation for the v3.1 ODS / API is available online at https://api.ed-fi.org/v3.1.0/docs/.
• Maintenance releases of the previous Ed-Fi ODS / API v2.x platform will continue to align with the Technology Suite Two version of the Ed-Fi Data Standard (currently, e.g., v2.0 and v2.2).

New & Improved Features

This section summarizes the major new features of the ODS / API v3.1. 

Support for Changed Record Queries

The goal of the changed record queries (or "change queries") feature is to surface information about the changes made to database tables to clients of Ed-Fi APIs. These changes include inserts, updates, and deletes. In previous versions of the ODS / API, client system developers had no way of identifying changes to records, which required client systems to request full datasets to overwrite or merge with their own information. The new change queries feature allows clients to request only data that has changed after a specified point in time.

The change queries feature is optional. The feature is turned off by default, and can be enabled by platform hosts via configuration. See the following documentation for details:

• The Changed Record Queries technical article contains detail for platform hosts, including how to enable the feature and detail behind the impact on the ODS data table structure.
• The Using the Changed Record Queries section in the API Client Developers' Guide provides how-to information for client systems. 
  

Improved Extension Support

Together with MetaEd v1.4, ODS / API v3.1 improves support for and resolves issues with multiple field extension scenarios. See ODS-2615 for details. 

Support for Multiple Operational Contexts

An operational context is a well-defined context in which a particular set of defined data values such as enumerations are used. The ODS / API v3.1 supports multiple operational contexts, and thus multiple enumeration sets. It does this primarily by providing mappings between different Ed-Fi Descriptor pattern value sets, and by allowing for an explicit declaration of operational context. 

Every instance of an ODS / API defines, and lives in an operational context. For example, a state-hosted ODS / API might be one operational context while a district in that state might host an ODS / API in a different operational context. Additionally, for interoperability reasons, client system vendors may want to develop general integrations outside the context of any specific host's operational context.

In v3.1 of the ODS / API, a host's operational context is defined in the "interop" schema in the ODS database. An API client could operate in the host context (e.g., as a SIS vendor) or a different context than the host (e.g., as a Transportation Vendor). The client operational context is associated with client key/secret in Admin database. The idea is that the API can translate the incoming values to the local context and the outgoing values to the requested operational context (using the Descriptor mappings stored in the local ODS database).

At this point, v3.1 builds the core operational context infrastructure and solves the use case for integration between the Ed-Fi ODS / API and the Ed-Fi Dashboards. Complete API-level mapping is on the roadmap for future releases of the ODS / API.

Date Changes to Support Multiple Assessments Per Day Per Student

Ed-Fi Data Standard v3.1 changed the Administration Date and Administration End Date on Student Assessment from a date to a datetime. This improvement allows for multiple assessments per day per student. The ODS / API v3.1 implements this improvement.

Datetime as a specific type for a single field is new to the ODS / API. For these new datetime fields, the ODS / API has the following behavior:

• On data in, clients should send datetime values in ISO-8601 format with a time zone designator (e.g., 2019-12-30T11:55:26Z). This can include an offset or can be expressed in UTC (i.e., with a zero offset). This approach avoids any ambiguity around the time zone. If the client system omits any precision information (which is allowable under ISO-8601), UTC is assumed.
• Data in the ODS is stored as UTC.
• Data is provided to clients in ISO-8601 UTC format.

This improvement also resulted in a few noteworthy refinements to API behavior:

• The ODS / API v3.1 rejects input if a datetime value is provided to a date-only field. Previous versions simply dropped the time-part if present.
• Previous versions returned a time-part even for date-only fields. The ODS / API v3.1 fixes this issue and only returns a date-part for date fields.

See the ODS / API v3.1 API documentation such as the studentAssessment endpoint for details.

Migration Support

The ODS / API v3.1 includes a migration utility that supports data migration from Ed-Fi Data Standard v2.0 and Ed-Fi Data Standard v2.2 to Ed-Fi Data Standard v3.1. The utility has out-of-the-box support for migrating an as-shipped ODS to the latest version. With additional customized scripting, the utility can be easily adapted and used to migrate extended ODS instances. ODS shared instances may take advantage of this utility. For year-specific instances, migration may not be a concern as a new ODS is created at the beginning of every school year.

The following table summarizes the supported scenarios for the migration utility:

See the Migration Utility documentation and the How To: Upgrade an ODS Database from Version 2.x to Version 3.1 article for more details.