Management of Valid School Years

[stephenfuqua]

How shall we manage valid school years in the new Ed-Fi Data Management Service?

The ODS/API has an endpoint, /ed-fi/schoolYearTypes, that allows a system host to modify the school years that are used in validating incoming POST and PUT requests. This endpoint is not part of the Ed-Fi Unifying Data Model (UDM), and thus is not a required part of the standard.

Typically, the organization hosting the API application is the one who would be controlling the valid years. For them, it might be more natural to configure the values at startup without having to use the API. In project Meadowlark, we took an approach of using environment variables to control the range of valid years. In the DMS, that would translate to appSettings values for the first and last valid year in the range.

What about situations where a managed service provider is hosting the API, but leaving questions of data management to their tenant? That is, the MSP in this scenario is only concerned about infrastructure, not data. (This is not the typical model today). In such a scenario, the tenant would probably be configuring their environment through a web application, and they would want to view the range of valid years and possibly update. In this case, it would make sense to include either a list of discrete school years (old style) or range (new style) in an API request, but that API request could not be to a running DMS instance: it would only make sense to configure this before setting up a tenant instance. In Project Tanager, that implies using a new interface in the Configuration Service.

In summary, there are two questions:

1. Store discrete valid years, or begin/end dates for a range of valid years?
2. Store these as
   1. App settings in the Data Management Service
   2. Via API call to the Data Management Service
   3. Via API call to the Configuration Service

Note

From a security standpoint, it probably makes more sense to use the Configuration Service than the Data Management Service, since the authorization pattern will be very different than for other resources in the DMS.

[vimayya]

While reviewing the UDM, I noticed that 'SchoolYearTypes' is not currently defined within it, even though it is referenced in other entities that form a part of the UDM. To ensure clarity and unambiguous usage within the UDM, it would be appropriate to explicitly define 'SchoolYear.'

In the earlier 2.x line, 'SchoolYear' was indeed part of the UDM. It seems, however, that it might have been omitted during the transition from Enumeration to Descriptor in the 3.x line.https://schema.ed-fi.org/datahandbook-v20/MetaEd-Handbook-Index.html#/SchoolYear231

It is important for API client to know valid values for the SchoolYear inorder to POST other resources that reference SchoolYear. E.g. gradingPeriods, sessions, graduationPlans. For that reason, /ed-fi/schoolYearTypes endpoint needs to exist.

'SchoolYear' is defined in the model https://github.com/Ed-Fi-Closed/Ed-Fi-Model/blob/DS-5.1.0-ME-3.0.0/Enumeration/SchoolYear.metaed. It's worth considering whether allowing free-form configuration by API hosts is appropriate.

[bradbanister]

I'm afraid SchoolYearTypes are special no matter what you do. They aren't like descriptors so they'll need their own reference validation scheme whether they are documents or config settings.

[bradbanister]

If it can be config, we can take care of validation at simpler/more performant document validation time (JSON Schema) rather than at the reference validation time.

[stephenfuqua]

Core requirement: must support all HTTP verbs for /ed-fi/schoolYearTypes. We can work out the details of how we store that information and use it in validation.

[bradbanister]

Could it just be that in practice for Tanager there are never claimsets that can PUT/POST/DELETE it?

[stephenfuqua]

Yes, that could be the case.

Also keep in mind though that we need the Resource API to be something that anyone can implement. It might be semantically weird for an API host to manage allowed school years through the Resource API in one situation, and manage it through a different backdoor when using the Tanager products.