[FEATURE] Documentation of roadway network schema and validation

[lmz]

User Story

As a modeler who builds networks, I would like to understand and (I'm guessing) take advantage of project card validation.

I noticed our script which applies project cards is passing validate=False. When I passed validate=True, I got errors because network_wrangler is trying to use yaml to load the non-yaml project cards (e.g. the .wrangler cards in this folder. I added a quick patch to skip those and I'm now getting this error:

2022-01-19 11:13:58, ERROR: Project Card Schema Loc:c:\users\lzorn\documents\github\network_wrangler\network_wrangler\schemas\project_card.json

So I was poking around the documentation/code/issues to understand what this schema is supposed to look like since it seems like we ought to create one but couldn't readily find much...

Priority

Medium ?

Level of Effort

For a bit of documentation, probably not huge?

Resolution Ideas

Project

MTC 😄

Who should be involved?

Implementer:
Commenters:
Users:
Reviewers:

Risk

Will this potentially break anything?

Tests

What are relevant tests or what tests need to be created in order to determine that this issue is complete?

[e-lo]

Short story: the json-schema needs to be updated to match currently used schema.

Issue #71 has this flagged.

[lmz]

Some questions/comments since my lack of understanding here has held me up for a bit with regards to this project.

1. From this doc (Understanding JSON Schema), "JSON Schema is a powerful tool for validating the structure of JSON data". However, we don't really keep our networks in JSON, we keep them in GeoDataFrames... and in fact I don't really like using JSON ever for this (Ability to do read/write in feather/parquet #198). Is JSON Schema still a useful tool or does something else make sense? I could be convinced that it is but...
2. I find the schema diffiult to read. I could make a bunch of effort, but it seems like making it understandable is important for network_wrangler usability. In which case, I think it would be helpful to have some version of it in the documentation that's better than this. Perhaps via JSON Schema for Humans which looks like it can make markdown which is more readable..? (I tried mkdocs-schema-reader briefly but it gave me an error.)
3. Assuming my first two points make sense, I think the documentation for the RoadwayNetwork needs to make clear that we're creating a network that adheres to a bunch of rules.
4. That's not even getting into the idea of user-specific variants of the schema, which I think we would want... or merging the schema with GMNS ([FEATURE] Merge the definitions of GMNS and wrangler network formats.  #306). 😁

[e-lo]

Updated schema docs to include validation scripts: 6f82ec2