/calendars and /calendarDates

The calendar endpoint represents a set of specific dates, typically instructional days.

The calendarDate endpoint specifies a particular date and includes additional information to describe the type of date (e.g., instructional day, make-up day, weather day, etc.).

Starting the 24/25 school year, an optional data collection to enhance the ability to perform additional data checks utilizing endpoints such as /calendars and /calendarDates.

This endpoint is OPTIONAL for both Public and Choice schools.

Ed-Fi Tech Docs: https://wisconsindpi.atlassian.net/wiki/spaces/widpiedfi/pages/246054913/calendars+and+calendarDates#Ed-Fi-Tech-Docs%3A-%5BhardBreak%5D

Data Properties:

#	Endpoint	Property Name	Data Type	Public (Required/ Optional/ Conditional)	Choice (Required/ Optional/ Conditional)	Business Definition
1.0	/calendars	calendarCode	string	Required	Required	The identifier for the Calendar.
2.0		schoolReference schoolId	big integer	Required	Required	The identifier assigned to a school. Format change from Integer to Big Integer (2025-26 SY and later)
3.0		schoolYearTypeReference schoolYear	integer	Required	Required	Key for School Year
4.0		calendarTypeDescriptor	string	Required	Required	Indicates the type of Calendar
5.0		gradeLevels gradeLevelDescriptor	string	Optional	Optional	Indicates the GradeLevel associated with the Calendar.
6.0	/calenderDates	calendarEvents calendarEventDescriptor	string	Required	Required	An unordered collection of calendarDateCalendarEvents. The type of scheduled or unscheduled event for the day.
7.0		date	string	Required	Required	The month, day, and year of the CalendarEvent.
8.0		calendarReference	array
9.0		calendarCode	string	Required	Required	The identifier for the Calendar.
10.0		schoolId	big integer	Required	Required	The identifier assigned to a school. Format change from Integer to Big Integer (2025-26 SY and later)
11.0		schoolYear	integer	Required	Required	The identifier for the school year associated with the Calendar.

Descriptors:

Endpoint	Namespace	Code Value	Short Description	Long Description

Endpoint	Namespace	Code Value	Short Description	Long Description
/calendars	uri://ed-fi.org/CalendarTypeDescriptor	Student Specific	Student Specific	Student Specific
		School	School	School
		IEP	IEP	IEP
		Grade Level	Grade Level	Grade Level
		Staff	Staff	Staff
	uri://ed-fi.org/CalendarEventDescriptor	Emergency day	Emergency day	Instruction cancelled or reduced due to an emergency
		Instructional day	Instructional day	Student instructional day
		Make-up day	Make-up day	Make-up instructional day
		Holiday	Holiday	Instruction cancelled or reduced due to a holiday
		Strike	Strike	Instruction cancelled or reduced due to a strike
		Teacher only day	Teacher only day	Non-instructional day for students designated for teachers (e.g., staff development, work day)
		Other	Other	Other
		Student late arrival/early dismissal	Student late arrival/early dismissal	Abbreviated instructional day due to student late arrival or early dismissal
		Weather day	Weather day	Instruction cancelled or reduced due to weather
		Non-instructional day	Non-instructional day	Non-instructional day
/calenderDates	uri://dpi.wi.gov/GradeLevelDescriptor	01	First Grade	First Grade ( 2026-27 SY)
		02	Second Grade	Second Grade ( 2026-27 SY)
		03	Third Grade	Third Grade ( 2026-27 SY)
		04	Fourth Grade	Fourth Grade ( 2026-27 SY)
		05	Fifth Grade	Fifth Grade ( 2026-27 SY)
		06	Sixth Grade	Sixth Grade ( 2026-27 SY)
		07	Seventh Grade	Seventh Grade ( 2026-27 SY)
		08	Eighth Grade	Eighth Grade ( 2026-27 SY)
		09	Ninth Grade	Ninth Grade ( 2026-27 SY)
		10	Tenth Grade	Tenth Grade ( 2026-27 SY)
		11	Eleventh Grade	Eleventh Grade ( 2026-27 SY)
		12	Twelfth Grade	Twelfth Grade ( 2026-27 SY)
		K3	3-year-old Kindergarten	3-year-old Kindergarten ( 2024-25 SY)
		K4	4-year-old Kindergarten	4-year-old Kindergarten
		KG	5 year old Kindergarten	5 year old Kindergarten
		PK	Pre-Kindergarten	Pre-Kindergarten ( 2026-27 SY)
	uri://ed-fi.org/GradeLevelDescriptor ( Added 2026-27 SY)	First Grade	First Grade	First Grade
		Second Grade	Second Grade	Second Grade
		Third Grade	Third Grade	Third Grade
		Fourth Grade	Fourth Grade	Fourth Grade
		Fifth Grade	Fifth Grade	Fifth Grade
		Sixth Grade	Sixth Grade	Sixth Grade
		Seventh Grade	Seventh Grade	Seventh Grade
		Eighth Grade	Eighth Grade	Eighth Grade
		Ninth Grade	Ninth Grade	Ninth Grade
		Tenth Grade	Tenth Grade	Tenth Grade
		Eleventh Grade	Eleventh Grade	Eleventh Grade
		Twelfth Grade	Twelfth Grade	Twelfth Grade
		Prekindergarten	Prekindergarten	Prekindergarten

Use Cases:

#	Use Case Title	Use Case Description	What to Submit/retrieve

#

Use Case Title

Use Case Description

What to Submit/retrieve

School Calendar

1.0

Sending the school calendar

The Calendar endpoint represents a set of specific dates, which usually represent instructional days.

If the school has only one calendar, then SIS vendors don't have to send the calendarReference on /studentSchoolAssociation.
Possible Calendar Types are: School, Grade Level, Student Specific, IEP, and Staff. DPI is not going to restrict the CalendarTypeDescriptor.
If a school has grade-level calendars, then there SHOULD be multiple Calendars and the GradeLevels on Calendar (Calendar.GradeLevel collection) for each SHOULD be populated and all calendar dates for that calendar populated. In this case there SHOULD NOT be an overall School calendar listing all GradeLevels, and such calendars should not attempt to show differences or "exceptions" from such an overall model.

----------------------------

The CalendarDate entity models a specific date, and allows additional information to describe the type of date.

SIS/LEAs are expected to report a CalendarEventDescriptor for all school days. Days that don't have a calendarDates resource are assumed to be an non-school days.
Possible Calendar Events are: Instructional day, Make-up day, Emergency day, Holiday, Strike, Teacher only day, Student late arrival/early dismissal, Weather day, Non-instructional day, and Other. DPI is not going to restrict the CalendarEventDescriptor.

POST on /calendars:

"calendarCode":"020TEST",
"schoolReference":
"schoolId":2097
"schoolYearTypeReference":
"schoolYear":2025
"calendarTypeDescriptor":"uri://ed-fi.org/CalendarTypeDescriptor#School",
"gradeLevels":[ ]

POST on /calendarDates (for each date):

"calendarEvents":
"calendarEventDescriptor": "uri://ed-fi.org/CalendarEventDescriptor#Instructional day"
"date": "2024-08-05",
"calendarReference":
"calendarCode": "020TEST",
"schoolId": 2097,
"schoolYear": 2025,

2.0

Sending multiple calendars

Schools in K12 often have multiple calendars. While schools may have an overall calendar that applies to everyone, others sometimes have slightly different calendars for various grade levels.

When using individual (or small group) calendars, it is RECOMMENDED that the StudentSchoolAssociation. Calendar reference only be populated when and if the student has a unique, individualized calendar, and not a school or grade level calendar. Such calendars SHOULD have a type set to a Ed-Fi standard descriptor value (e.g., "Student Specific" or "IEP") to ensure clarity on the scope and avoid confusion with a school or grade-level calendar. "

If the school has only one calendar, then SIS vendors don't have to send the calendarReference on /studentSchoolAssociation.
If the school if there are multiple calendars, SIS vendors must send the calendarReference on /studentSchoolAssociation.

POST on /calendars: -- overall calendar that applies to everyone
"calendarCode":"030TEST",
"schoolReference":
"schoolId":7522
"schoolYearTypeReference":
"schoolYear":2025
"calendarTypeDescriptor":"uri://ed-fi.org/CalendarTypeDescriptor#Grade Level",
"gradeLevels":
"gradeLevelDescriptor":"uri://dpi.wi.gov/GradeLevelDescriptor#6",
"gradeLevelDescriptor":"uri://dpi.wi.gov/GradeLevelDescriptor#7"

POST on /studentSchoolAssociation:
"entryDate": "2025-08-05",
"calendarReference":
"calendarCode": "030TEST",
"schoolId": 7522 ,"schoolYear": 2025,"schoolReference": "schoolId": 7522"studentReference": "studentUniqueId": xxxxxxxetc......----------------------