The agreed shape

Think of it when two programs pass the same data between them, or a field is about to change name or type.

In everyday life

A paper form that every office in a town copies from. Move the “date of birth” box, and every clerk who still reads the old spot copies the wrong thing, without complaint.

One case

A school’s grade system saves each test result with a field called “score”. A developer renames it to “points”. The report card service still reads “score”, finds nothing, and prints 0 for every test marked after the change. Nothing crashes, so nobody notices until parents write in.

The field was renamed after test #102
The case, cell by cell1 cell = 1 test result
Score the teacher gave
728564907858
Score on the report card
72850000
Tests shown as 0
4
Errors logged
0
The grade system wrote “points”; the report card service still read “score”.

Every case

Data lives longer than the code that wrote it, and many programs read it. The schema is the contract between all of them. Change it without telling every reader, and the readers break, often without an error: they show empty, zero or wrong values.

The word

Engineers call this

schemaThe agreed shape of a piece of data: which fields it has, and the type of each field. Every program that reads or writes the data depends on it.

Agree the shape before you build, write it down in one place, and change it only in steps that every reader survives.

Where this idea leads

Skills that encode it

  • principle-type-system-discipline pstack“Derive types from authoritative schemas”: one file owns a shape, and every reader takes its types from it.
  • typescript-best-practices pstack“Schemas before guards”: define the shape once in a runtime schema and infer the type from it.