Formalize data dictionaries / metadata?

[jpn--]

As we currently have set up ActivitySim, there are a number of different ways that we have "data dictionaries" that translate coded variables into meaningful names:

• free-floating tables on documentation pages
• organized in a wiki
• implicitly coded as constants in model specification files
• not having a publicly available dictionary at all

Sometimes more than one of these are employed, and sometimes they have conflicting definitions (oof!).

It might be useful to establish a formal expected format of data dictionaries (e.g. a YAML spec), which could be committed directly to version control along with a model definition. This could be useful in (a) automatically validating input data, and (b) constructing visualizations that can be enhanced with meaningful descriptions.

One of the downsides of adding such a formatting spec is that, unless agencies can use this instead of what they do now, it will add an additional layer of things that model developers/editors need to maintain -- or risk getting out of sync and having even more conflicting definitions.