SideDoc

Appearance

ADR 0004: Profiles are generated from a Google Sheet ​

  • Status: accepted
  • Date: 2026-05-18 (schemas repository initialised with the generator)
  • Evidence: schemas repository GenJSONSchema/schemaGen.py, build.sh (sheet id and one tab per profile), scripts/ (vocabulary conversion, linting, DCAT-AP tabs)

Context ​

The datasheet fields are defined with domain experts who do not edit JSON Schema. The field list changes often, each field has several properties (label, occurrences, type, multilingual, vocabulary, UI hint, DCAT-AP mapping notes), and several profiles share one type library. Review already happened in a shared spreadsheet, with comments per row (for example on DCAT-AP alignment).

Decision ​

  • The Google Sheet is the source of truth for profiles. One tab holds the type library, one tab each profile (datasheet, NDE dataset, NDE catalog, DCAT-AP dataset).
  • GenJSONSchema/schemaGen.py reads a tab (public TSV export, or the Sheets API with a service account for private sheets) and writes JSON Schema 2020-12: the type library in $defs, and profiles that $ref it. Field metadata goes into x-sidedoc (id, labels, occurrences, type, UI hint, vocabulary binding).
  • build.sh runs the generator for every profile of the version in VERSION, post-processes the output, and refuses to overwrite a published version unless FORCE=1 is set.
  • Published schemas are immutable per version (sidedoc.app/schemas/<version>/). A change that alters document shape bumps the version.

Consequences ​

  • Domain experts can change fields without a developer; developers review the generated diff.
  • The editor must render from the schema alone, with no per-field code (Editor rendering). Field ids (ds:f00100) are stable keys for help texts and mapping rules.
  • The sheet is an external dependency: generation needs network access, and private sheets need a service account.
  • Things the sheet cannot express are added in build.sh post-processing (for example x-exports, docsSchemaUrl) or kept in separate files (help texts, ADR 0005; mapping files, Exports and mappings).