IF Commons GitHub

sql-describe

0057Active

0057-sql-describe · owner if · domain data

Requirements

FR-001checkpassing

describeModels MUST compose the modules, project them and bind them for each dialect it is given, and give one described model for each module, or say why the composition, the projection or the binding failed.

Enforced (check): .github: cd commons/data && bun run verify — suite/describe.test.ts: a model is described in three layers, one described model for each module: governance (module, concept, attribute, relationship, code list, code), logical (table, column, keys, indexes) and physical (the SQL of each dialect, the typed table), each element with a stable id

Proved by: data/suite/describe.test.ts

Written in: data/sql/describe/mod.ts

Tests: passed: suite/describe.test.ts a model is described in three layers, one described model for each module: governance (mod

FR-002checkpassing

A described model MUST have the three layers (governance, logical, physical), each with a title and a summary that says what the layer is, which code writes it and whether it may be edited, and the kinds of element it holds.

Enforced (check): .github: cd commons/data && bun run verify — suite/describe.test.ts: a model is described in three layers, one described model for each module: governance (module, concept, attribute, relationship, code list, code), logical (table, column, keys, indexes) and physical (the SQL of each dialect, the typed table), each element with a stable id

Proved by: data/suite/describe.test.ts

Written in: data/sql/describe/mod.ts

Tests: passed: suite/describe.test.ts a model is described in three layers, one described model for each module: governance (mod

FR-003checkpassing

A described model MUST have, with a stable id each (unique within the model, of the form layer:...): in governance its module, concepts, attributes, relationships, code lists and codes, each with its definition and what is said of it (identity, datatype, multiplicity, annotations); in logical the tables, columns, foreign keys, uniques and indexes it owns; in physical the SQL of each table for each dialect and the typed table that reads and writes it.

Enforced (check): .github: cd commons/data && bun run verify — suite/describe.test.ts: a model is described in three layers, one described model for each module: governance (module, concept, attribute, relationship, code list, code), logical (table, column, keys, indexes) and physical (the SQL of each dialect, the typed table), each element with a stable id

Proved by: data/suite/describe.test.ts

Written in: data/sql/describe/mod.ts

Tests: passed: suite/describe.test.ts a model is described in three layers, one described model for each module: governance (mod

FR-004checkpassing

A described model MUST trace each governance concept to its table, each attribute and relationship to its columns, and each table to its SQL for each dialect and to its typed table; every end of a trace MUST be an element of the models; the typed table MUST name a file and an export that exist.

Enforced (check): .github: cd commons/data && bun run verify — suite/describe.test.ts: every element of one layer is traced to what it is made into, every end of a trace is an element, and the typed tables the physical layer names exist in the generated files

Proved by: data/suite/describe.test.ts

Written in: data/sql/describe/mod.ts

Tests: passed: suite/describe.test.ts every element of one layer is traced to what it is made into, every end of a trace is an e

FR-005checkpassing

The same models MUST give the same bytes as JSON, and the source of an element (a file and a line) MUST be what the caller's locate says of it, none where it says none.

Enforced (check): .github: cd commons/data && bun run verify — suite/describe.test.ts: the same models give the same bytes, as JSON, and the source of an element is what the caller says of it

Proved by: data/suite/describe.test.ts

Written in: data/sql/describe/mod.ts

Tests: passed: suite/describe.test.ts the same models give the same bytes, as JSON, and the source of an element is what the cal

FR-006checkpassing

What has no definition (a module, a concept, an attribute, a relationship, a code list), a concept identified by nothing, a code list with no code, and personal data held for no purpose MUST each be a finding that names the element and says what to do; the models of this library MUST have none.

Enforced (check): .github: cd commons/data && bun run verify — suite/describe.test.ts: what has no definition, an identity or a purpose is a finding that names the element; the real models have none

Proved by: data/suite/describe.test.ts

Written in: data/sql/describe/mod.ts

Tests: passed: suite/describe.test.ts what has no definition, an identity or a purpose is a finding that names the element; the

Out of scope

  • Operations and invariants, issues and the SQL-DQ tests of a model: later parts, as elements of the same layers.
  • Writing pages and files: the generator's lens does it (commons 0011-documentation FR-029).
  • Models of other libraries (the headless command model): each library describes its own.

Edge cases

  • A module that owns no table (a module of concepts that another projects) is described with its governance elements alone, per FR-003.
  • A foreign key to a table of another module references that table's element, which is in another described model, per FR-004.
  • A concept that cannot be located by the caller has no source, which is not a finding, per FR-005.

Assumptions

  • The element ids are the keys of links and of diffs between releases: a rename is a removal and an addition.
  • The caller finds where values are written from the exports it imports; this unit reads no source file.

Open questions

OQ-1open question

Whether an operation (governance's operation) becomes an element of the governance layer with a trace to its SQL routine, or stays with the library that implements it.

Key entities

  • Described model - the layers, elements, trace and findings of one module.
  • Element - one thing a layer says, with a stable id.
  • Trace - an element of one layer made into an element of another.

Success criteria

SC-001success criterion

An agent that is given only a described model (as JSON) can say which file to edit to add an attribute, which command regenerates what follows, and what will change in each layer.

Review & acceptance checklist

  • [x] Every requirement is testable (MUST / MUST NOT), not aspirational
  • [x] No company fact is asserted here
  • [x] Every open item is marked, not silently decided

Cited by

Data, sql/describe/mod

Titles, headings, exports, tables, columns and requirements. Esc closes.