Proposal: Standardized Course and Schedule format

Introduction

A standardised format for representing the schedule of classes is needed for maintaining stability and easing maintainability. It's easier to account for special cases when they're in the correct format and any data sources such as the SOC, Jarrin's excel sheet and other scrapers should be made to conform to the format.

From a students perspective, we're improving on the https://enr-apps.as.cmu.edu/open/SOC/SOCServlet page and would be an advanced drop in replacement for it. That means we need also need to consider auxiliary information about courses as well such as the description.

Format Requirements

Semester metadata
- Semester Name
- Shortcode
- Last Update (When source was retrieved, ISO 8601 format)
- Schedule ID (A unique hash of length 5)
Course code
Course title
Units
Description
Prereqs
Coreqs
Sections
- Instructors
- Times
- Days

Proposed JSON format

A JSON format would work really well with a web frontend since its easy to create into javascript objects and also to deal with in a python backend. Dealing with intricacies such as multiple sections is also made easier by adding them to a sections array.

The format is simple but the following rules are in place:

Course Codes should follow the XXXXX format not XX-XXX
Class Times follow a 12 hour format eg XX:XXPM
- Semester metadata needs to include the full date follows ISO 8601 format)
Prereqs and coreqs support stellic and SOC format
- They are case insensitive and support clauses
- Eg. SOC gives us (12202 and 15122) and (15251)
- Eg. Stellic gives us (15-122 Minimum Grade C) but course format should change to XXXXX
Days follow the "UMTWR" format
Lectures and Recitation pairs should be ordered consecutively, and correctly labeled for the sections array
If values are missing they should have "UNK"
All numerical figures are in string format, the end user needs to deal with conversion

{
  "semester_name": "Fall 2024 Students",
  "semester_shortcode": "F24",
  "last_update": "2024-05-19T14:35:46.960741+00:00",
  "ID": ,
  "courses": [
    {
        "course_code": "03151",
        "course_title": "Honors Modern Biology",
        "units": "10",
        "description": "REMOVE FOR BREVITY",
        "prereqs": "None",
        "coreqs": "None",
        "sections": [
          {
            "section_type": "Lecture",
            "section_id": "Lec 2",
            "timings": {
              "days": [
                "UTR"
              ],
              "begin": "10:00AM",
              "end": "10:50AM",
              "teaching_location": "Doha, Qatar",
              "delivery_mode": "In-person Expectation",
              "instructor": [
                "Affara, Nesrine"
              ]
            }
          },
          {
            "section_type": "Recitation",
            "section_id": "W",
            "timings": {
              "days": [
                "R"
              ],
              "begin": "03:45PM",
              "end": "05:35PM",
              "teaching_location": "Doha, Qatar",
              "delivery_mode": "In-person Expectation",
              "instructor": [
                "Affara, Nesrine"
              ]
            }
          }
        ]
      }
   ]
}

open-cmuq / schedule-genius