HomeSoftware Heritage

sql/json/: first stab at documenting JSON(B) values using JSON Schema

Description

sql/json/: first stab at documenting JSON(B) values using JSON Schema

This is still very preliminar. I've merely extracted all examples from
the current real DB, looking at all columns with type JSON or JSONB.
Based on the examples I've documented all properties, applying the most
reasonable types. The largest example is the revision.metadata column.

A lot of documentation work is still missing;

  • required properties are not declared (but should, most notably in revision.metadata, given that a large part of that schema is valid only for Debian packages). Note that by default in JSON Schema all properties are *optional* so this aspect shoult not affect validity
  • title/description generic properties are seldomly used and should be used more
  • default generic property is never used, but probably should

On the validation front we should:

  • validate all JSON(B) values in the DB against these schemas. Some upcoming validation errors are already evident. In particular: tarball artifacts do not have a "length" property, and symmetrically debian source package artifacts lack an "archive_type" property
  • validate the JSON Schema itself, as I might have gotten the spec wrong

Details

Provenance
zackAuthored on Mar 4 2016, 5:28 PM
zackPushed on Mar 4 2016, 5:36 PM
Parents
rDSTO9ec836ed10f8: storage: add entity_get_one to retrieve a single entity
Branches
Unknown
Tags
Unknown