hubverse-org / hubAdmin

Utilities for administering hubverse Infectious Disease Modeling Hubs
https://hubverse-org.github.io/hubAdmin/
Other
1 stars 2 forks source link

Add class to output of `json_validate()` for compact printing #32

Closed zkamvar closed 2 months ago

zkamvar commented 3 months ago

At the moment, the output of any of the validation functions is the output of jsonvalidate::json_validate(), which is a boolean with an "errors" attribute appended when there are errors.

While we return this boolean to the users, errors and all, when there are errors in a deeply nested region of the JSON or a lot of little errors, it's difficult to understand what the object actually is.

Since we return this to the user, we can add a class to it and a print method that gives a summary of the errors and how to use the object (and even links to the schema with the recent update to {cli}).

annakrystalli commented 3 months ago

This is really the purpose of view_config_val_errors()?

zkamvar commented 3 months ago

That's true, but it's a two-step process. Even in the case of valid config files, which don't use view_config_val_errors(), the output is still not easy to interpret even for R practitioners:

validate_config(
  hub_path = system.file("testhubs/simple/", package = "hubUtils"),
  config = "tasks",
  schema_version = "latest"
)
#> ✔ Successfully validated config file /home/runner/work/_temp/Library/hubUtils/testhubs/simple/hub-config/tasks.json against schema <https://raw.githubusercontent.com/hubverse-org/schemas/main/v3.0.1/tasks-schema.json>
#> [1] TRUE
#> attr(,"config_path")
#> /home/runner/work/_temp/Library/hubUtils/testhubs/simple/hub-config/tasks.json
#> attr(,"schema_version")
#> [1] "v3.0.1"
#> attr(,"schema_url")
#> https://raw.githubusercontent.com/hubverse-org/schemas/main/v3.0.1/tasks-schema.json

When I look at how {jsonvalidate} is used across R packages, it seems that they either return TRUE or fail/warn with the output of the error attribute. It makes sense because {jsonvalidate} is not really meant to be an end-user-facing package.

Having these outputs is great for being able to program on for future use, but it's not a great user experience to scroll up lines and lines of output to see the results of the checks (IIRC, this was one of the motivations of {tibble} and {data.table} outputs).

In my own experience, it took me a couple of minutes to understand what the output of validate_hub_config() was telling me, but ultimately there are two scenarios that I as a hub administrator would care about:

  1. the hub is correctly configured
  2. the hub is incorrectly configured and where

For the second scenario, we could print something like this (with formatting clickable links via {cli}):

hub incorrectly configured:
 - /path/to/tasks.json (via [tasks v.3.0.1](https://path-to-schema)): 3 errors
 - /path/to/admin.json (via [admin v.3.0.1](https://path-to-schema)): ok
 - /path/to/model-metadata.json (via [model-metadata v.3.0.1](https://path-to-schema)): missing
use `view_config_val_errors(res)` to view the errors in a table.
zkamvar commented 3 months ago

And another benefit: this would vastly reduce the size of the vignette (e.g. I have to scroll six pages on my monitor for a total of four errors in the validate_config() example).

annakrystalli commented 3 months ago

Ah ok. Yes I was focused on directing hub admins to the actual details of the errors which was super hard to navigate but a nice summary print method is indeed much nicer!