Skip to main content

Formats and Schemas

What this concept is​

A format specifies how values are arranged in text or bytes. A schema specifies the structure and types your application expects. CSV is useful for rows; JSON can represent lists and named objects. A valid document in either format can still be invalid for your application.

Why it matters here​

You will import study sessions and produce a reusable report. Choosing a small explicit shape makes the tool testable and prevents the parser from guessing what a row meant.

Concrete example​

The record "Reading, notes",25 has two CSV fields, not three: the quoted comma belongs to the topic. Splitting each line on commas loses that distinction. The CSV library understands the quoting rules. JSON {"minutes": "25"} holds text; {"minutes": 25} holds a number. The appearance of digits does not erase the type difference.

Our lab accepts exactly the header topic,minutes. It strips surrounding whitespace from each data field, requires a nonempty topic, and accepts only ASCII decimal digits representing 1–240 minutes. A header-only file is valid empty data. Blank data records are rejected. These are declared local rules, not universal CSV requirements.

Common confusion / misconception​

Do not build a universal parser from a few examples. Commas, quotes and embedded newlines interact. A schema stricter than another application's schema is not necessarily a bug, but it must be documented. CSV has no automatic integer type.

How to use it​

Write a valid example, an empty example and three invalid examples before parsing. Name permitted fields, missing-field behavior, types and ranges. Use the standard CSV parser, then check its output. Keep record numbers distinct from physical line numbers when quoted fields contain newlines.

Check yourself​

Should Python,25,extra quietly discard the last field? No. This module's two-field contract rejects it. Does valid CSV imply valid minutes? No.

Mini drill or application​

Write a quoted-comma record and compare a manual comma split with csv.reader. Draw the corresponding JSON object with a numeric minutes field. Explain what each format preserves.

Read this only if stuck​

Python CSV documentation explains parser usage; JSON documentation explains value conversion. The exact session schema is defined by our lab README.