Skip to content
All notes

The schema is the contract

Note 2 of 12
  • #astro
  • #content
  • #systems

content.config.ts is the one file every page builds against. Making the notes tier cheap meant deciding what it is allowed to require.

The three content tiers are defined in one file, src/content.config.ts, and everything else on the site reads from it. Index pages, templates, the feed. If a field is not in the schema, no page can depend on it. If a field is required, every entry has to carry it or the build fails.

That makes the schema the place where the publishing cost of each tier actually gets set. Not the design. Not the writing. The required fields.

So notes require 3 things: title, date, tags. The summary field is optional on purpose, because a note that is only worth 200 words is often not worth writing a second, shorter version of. The draft flag defaults to false.

Guides require summary, because a guide with no meta description is a guide that will not rank, and carry a noindex flag because 2 existing guides deliberately stay out of search.

Artifacts require kind and trigger, and it is the second one that earns the tier its place. An artifact page that does not say when you would reach for the thing is just a code listing.

The useful discipline here is that adding a required field is a tax on every future entry in that tier, forever, paid at the moment you are least willing to pay it. A field that seems obviously worth having in the abstract is the field that stops you publishing on a Tuesday night.

The build failing on a missing field is the point. It is also the reason not to require much.

I tested this on myself while writing the first batch. Halfway through I wanted a reading_time field, then a related array, then a hero image. Each one felt small. Each one would have been 12 edits to backfill and one more decision to make every time I open a new file. None of them went in. A note that needs a hero image is a guide.

There is a version of this file that requires 9 fields per note and produces a beautiful index page nobody ever adds a row to. I have written that site before. This time the schema is the thing I am protecting.

If I later find myself adding an optional field so that notes can be a bit more like guides, that is the tier collapsing and I should stop.

Back to all 12 notes