Table Schema: contextual metadata about the schema

I would find very usefull to build schema documentation based on Table Schema. That way documentation and data would stay closed together, because the schema can also be used for validation with CSV Lint.

To do that, we need contextual information about the schema: its title, author, version, and so on… Here is an example to show what I would find useful:

{
    "schema": {
      "title": "Spécification de la liste annuelle des prénoms des nouveaux-nés",
      "author": "Charles Nepote <[e-mail]>",
      "date": "mars 2017",
      "version": "0.1beta",
      "description": "La liste annuelle des prénoms des nouveaux-nés est un jeu de données simple et très apprécié du public. Il consiste en une liste de prénoms avec l'occurence de chacun pour une année donnée.",
      "fields": [
        {
          "name": "CODE_INSEE",
          "title": "Code INSEE",
          "description": "Code INSEE de la commune où les prénoms sont enregistrés. Issu du Code officiel géographique, est composé de 5 caractères alphanumériques (les deux premiers correspondent au département et peuvent donc contenir les lettres A et B, utilisées pour la Corse).",
          "type": "string",
          "examples": "06088, 1B002 (pour une commune corse)",
          "constraints": {
            "required": true,
            "pattern": "^([013-9]\\d|2[AB1-9])\\d{3}$"
          }
       ]
    }
}

I made a very quick and (very) dirty tool to show that. Unfortunatly, it’s only in french for the moment, I’ll translate it if you’re interested in: http://dataliteracyconference.net/specificator/demo3.html (link will change).

Adding some contextual informations won’t break anything, I think. And open data movement needs more professionnal yet simple tools. Thanks for your efforts!

[cbenz]

Just to let you know, we generated a Gitbook documentation of some schemas we are using, based on the enhancements proposed by @CharlesNepote, sightly adapted.

For example:

• schema: https://git.opendatafrance.net/scdl/subventions/blob/master/schema.json
• generated doc : https://dev.validata.fr/docs/schemas/scdl-subventions.html
• generation script : https://git.opendatafrance.net/validata/validata-doc-generator/blob/master/table_schema_to_md.py

I intend to propose a “pattern” as suggested above, in the next weeks, to reopen the discussion about adding metadata to table schemas, on a concrete base.

[johanricher]

@rufuspollock @pwalsh @frictionlessdata Our team at @jailbreak-paris has increasingly used Table Schema for the past year and a half and we’re seeing more and more adoption around us (including at @Etalab). We think it has a bright future. So we’ve finally rolled up our sleeves and (finally!) got to work on this. Our draft propostion and (most importantly) questions are here: https://github.com/frictionlessdata/specs/pull/627