Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[FEATURE] Documentation of roadway network schema and validation #278

Closed
lmz opened this issue Jan 19, 2022 · 3 comments
Closed

[FEATURE] Documentation of roadway network schema and validation #278

lmz opened this issue Jan 19, 2022 · 3 comments
Assignees
Labels
enhancement New feature or request
Milestone

Comments

@lmz
Copy link
Collaborator

lmz commented Jan 19, 2022

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?

@lmz lmz added the enhancement New feature or request label Jan 19, 2022
@e-lo
Copy link
Collaborator

e-lo commented Jan 19, 2022

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

Issue #71 has this flagged.

@lmz
Copy link
Collaborator Author

lmz commented Mar 10, 2023

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 e-lo added this to the v1.0 milestone Mar 15, 2023
@e-lo e-lo self-assigned this Mar 15, 2023
@lmz lmz changed the title [FEATURE] Documentation on project card schemas and validation [FEATURE] Documentation on network-wrangler schemas and validation Mar 15, 2023
@e-lo e-lo changed the title [FEATURE] Documentation on network-wrangler schemas and validation [FEATURE] Documentation of roadway network schema and validation Mar 15, 2023
@e-lo
Copy link
Collaborator

e-lo commented Aug 27, 2024

Updated schema docs to include validation scripts: 6f82ec2

@e-lo e-lo closed this as completed Aug 27, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request
Projects
None yet
Development

No branches or pull requests

2 participants