The notebook index
Earlier notes
Earlier reference notes remain available at their existing addresses. The current blog concentrates on programming languages, protocols and self-hosted software.
310 notes.
- When Should a Public Data API Use JSON or CSV?
Choose a format by the shape of the data and the work clients need to do: JSON supports nested structures, while CSV is convenient for flat tables.
- Why Should API Fields Include Units?
A numeric value has little meaning until clients know its unit, scale, and measurement context.
- How Can a Dataset Represent Unknown Values?
Define what missing fields and explicit nulls mean, and keep unknown data distinct from valid zeroes and empty text.
- What Makes a Timestamp Unambiguous in JSON?
Include a complete date and time with either a UTC marker or an explicit offset so clients can place an event on a shared timeline.
- What Is the Difference Between a Record and a Field?
A record groups the properties of one entity, while a field names one property shared by records in a dataset.
- How Can a Schema Describe Optional Data?
A useful schema says which fields may be absent and gives omission and null distinct, predictable meanings.
- Should an API Return Numbers as Strings?
Return quantities as numeric values for calculation, while reserving strings for identifiers and values whose exact formatting matters.
- How Do You Represent Coordinates Without Confusing Latitude and Longitude?
Name coordinate axes explicitly and document their order, units, and reference system so clients place points correctly.
- What Is a Stable Identifier for a Public Dataset Record?
A stable identifier keeps pointing to the same entity across dataset updates, with its scope and reuse rules clearly documented.
- How Should a Dataset Version Be Represented?
Give every published snapshot a clear release identifier and explain how clients can relate it to the data they downloaded.
- Why Should a Data Format Preserve Original Values?
Normalization improves consistency, but retaining source values can preserve distinctions needed for auditing and future reinterpretation.
- How Can an API Describe Enumerated Values?
List allowed values, explain what each means, and describe how clients should handle future additions.
- What Should a Machine-Readable Error Look Like?
Return a predictable error shape with a stable code and helpful message, while keeping implementation details private.
- How Do You Model a Reading and Its Measurement Time?
Represent a measurement with its value, unit, observation time, and source identity so clients can interpret and trace it.
- What Is the Difference Between Empty Text and Null?
Empty text can assert that a value is known to contain nothing; null can signal that no value is available. Treating them as interchangeable erases useful information.
- How Should Large Data Responses Be Paginated?
Reliable pagination depends on a deterministic order and a continuation rule that remains valid as clients request later pages.
- Can CSV Express Nested Data Reliably?
CSV is useful for rows and columns, but relationships and nested values require explicit conventions or a companion structured representation.
- How Do You Document a Data Dictionary?
A useful data dictionary explains what each field means, how it is represented, and what a reader can safely infer from it.
- What Does Backward Compatibility Mean for an API Schema?
A schema change is backward compatible when existing clients can continue to interpret responses and requests under the old contract.
- How Should a Dataset Represent a Time Interval?
An interval needs clear endpoint rules, a time basis, and a consistent representation so users can determine exactly which moments it covers.
- Why Is Text Encoding Part of Data Quality?
A correct dataset can become corrupted when software interprets its bytes using the wrong text encoding.
- How Can a Data Format Distinguish Observation from Estimate?
A value alone may not reveal whether it was measured, calculated, interpolated, or forecast. Record the method or status alongside it.
- What Is a Useful Exercise for Inspecting a GTFS Table?
A short inspection exercise can teach how a GTFS file's columns and rows express a transit dataset's concepts.
- How Should Data Sources Be Attributed in an Export?
Attribution should give a recipient enough information to identify the input dataset, its terms, and the process used to create the export.
- What Is the Risk of Using Floating-Point Values for Identifiers?
Identifiers label entities; floating-point numbers represent approximate quantities. Using one for the other can change values or their meaning.
- How Can a Schema Handle Future Fields?
A schema should tell clients how to behave when new fields appear, so evolution does not turn ordinary additions into failures.
- Why Should Public Data Include a License Statement?
A download's availability does not by itself explain the terms under which others may copy, adapt, or redistribute the data.
- How Do You Represent a Schedule Time Beyond Midnight?
Some transit service days extend past midnight, so schedule times need to remain attached to the service day that defines them.
- What Makes a Data Export Reproducible?
A reproducible export records enough inputs and transformation details for someone to understand or regenerate the same result.
- What Does It Mean for a Function to Be First-Class in C?
C functions can be selected at runtime by passing and storing pointers to them. A small callback illustrates what that enables and where C’s syntax differs from languages that treat functions as ordinary values.