Consider treating check-jsonschema as an "official" more featureful CLI

[sirosen]

Huge Disclaimer: I'm the author/maintainer of check-jsonschema so obviously I think it's great and we should all use it. 😉

There are a number of issues which revolve around making the jsonschema CLI more featureful.
I think it's nice to have a built-in CLI, but that it's also nice to keep the complexity of this project low and have a clear separation of concerns.

check-jsonschema currently takes care of the following features which I do not believe should be features of jsonschema:

• providing a pre-commit hook (see also pre-commit integration v2 #857 and related)
• supporting YAML as a format (solves Support for other file formats in the CLI #582)
• downloading and caching schemas specified as HTTP(S) URLs
• vendoring a set of known schemas as part of the package, to support offline usage (e.g. in pre-commit.ci)
• some controls over format validation

Because the version number of check-jsonschema moves independently from jsonschema, it's not necessary to do a jsonschema release in order to update the pre-commit hook config or add CLI-only features. And it's not necessary to think about a major version bump in order to change the CLI in a breaking way.

Many CLI features, like #889, could be handled by check-jsonschema, allowing this project to ignore them.

The most significant downside I know of is that check-jsonschema has very rudimentary output formatting. It's nowhere near as nice as the jsonschema CLI (yet!).

Here are some ideas I've had about what we can do if this is interesting:

• listing check-jsonschema in the "Community" section of the readme
• adding a link somewhere in the docs
• creating a github org (py-jsonschema?) and putting both projects under it

I'm also willing to make changes in check-jsonschema if there is some milestone the project must meet (other than popularity) in order to be considered.

[Julian]

Hi. Thanks for the ticket. I'll leave longer comments, but a quick one is that the CLI is functionality I didn't want to add in the first place :), I wanted someone doing it as an additional package, so I'm definitely open to the idea.

What needs to change or how probably are longer and require some investigating, but yeah thanks definitely worth discussing.

[sirosen]

I don't want to pollute the issue tracker here, but I've been working on trying to make sure check-jsonschema covers all of the use-cases which have been raised about the CLI on this project.

@Julian, with your permission, I'd like to add replies to the following issues suggesting that they use check-jsonschema to see if it satisfies their needs:

• Validate date-time via CLI #913
  "format" validation is enabled by default in check-jsonschema
• CLI does not accept a schema without instance any longer #889
  I've added a --check-metaschema flag, and accepted the complexity it adds.
• Support specifying a base URI explicitly to the CLI #669
  The local file loading behavior in check-jsonschema uses a RefResolver where the ref-base is the filename. I think that will satisfy this user.
• Support for other file formats in the CLI #582
  As I'm trying to build a tool for validating yaml files like .readthedocs.yml, this is one of my primary features.

I believe that all of these (and probably some closed issues too) could be considered "solved" by this.

---

I'm trying to balance how much self-promotion is appropriate here, vs how useful it would be to tell people about the tool. Please let me know if it seems like I'm crossing the line! It's hard to figure out. 😅

[Julian]

Thanks! So far how you've gone about this is perfect, so don't worry :)

I'm thinking perhaps we take things the org route -- I'll create a python-jsonschema org, and add you to it. We can then discuss any changes, but at least it gets things underway. -- Which apologies I still haven't really taken a close look, so the only thing I'm not 100% thrilled yet about is the precise name, but it seems jsonschema-cli is unfortunately taken :/

But yeah let me create the org.

Until then, definitely feel free to promote on those issues!

[sirosen]

I'll create a python-jsonschema org, and add you to it. We can then discuss any changes

Woohoo! We'll figure out more later, I'm sure.

Which apologies I still haven't really taken a close look

No need to apologize! I'm not expecting your review -- though obviously I'd appreciate it.
check-jsonschema is staying in 0.x versions until I'm confident that the code isn't going to need (another) major rewrite. So there's plenty of time for you to look in the future if you want.

the only thing I'm not 100% thrilled yet about is the precise name, but it seems jsonschema-cli is unfortunately taken :/

We could try to reclaim that name, but I must admit that I don't really like "jsonschema-cli".
I like some verb in there like check or validate OR something which isn't hyphenated at all like rustc or jq (I just can't come up with a good one for this).

We can revisit later: I'm not super strongly attached to the current name -- we can look at doing a name-change in the future if it seems worth it.
The only thing I think is important is to have the package name and command name match because it's easier for people to learn and use.

[sirosen]

v0.15.0 of check-jsonschema added a lot of what I felt was missing, so I'm now thinking about what it takes to consider this issue closed.

I think the next stage is to start closing any outstanding issues for the CLI component and pointing them at check-jsonschema.

We can close this issue or keep it open -- either is fine by me.

[Julian]

Congrats! I'm happy with that. I honestly owe checking the CLI out again just so I'm not an ignoramus about its functionality, but yes agree! Let's close and start redirecting folks!