jsonschema

jsonschema copied to clipboard

I haven't had time to focus on jsonschema typing much recently, but I want to get things back on track. The first thing to do is to correct any drift between jsonschema and typeshed. I'm going to try to produce a steady stream of very small PRs which get things back in sync.

This is therefore hopefully the first of a few changes.

---

python/typeshed#8608 introduced annotations for create which are not fully reflected here.

In order to reflect that state into jsonschema, a new module, jsonschema._typing is introduced. The purpose of _typing is to be a singular place for the library to define type aliases and any typing-related utilities which may be needed. This will let us use aliases like _typing.JsonValue in many locations where any valid JSON datatype is accepted. The definitions can be refined over time as necessary.

Initial definitions in _typing are:

• Schema (any JSON object)
• JsonObject (any JSON object)
• JsonValue (any JSON value, including objects or sequences)

Schema is just another name for JsonObject. Perhaps it is not needed, but the name may help clarify things to a reader. It is not obvious at present whether or not it is a good or bad idea to notate it as such, but a similar Schema alias is defined in typeshed and seems to be working there to annotate things accurately.

These types are using Mapping and Sequence rather than dict or list. The rationale is that jsonschema's logic does not dictate that the objects used must be defined in stdlib types or subtypes thereof. For example, a collections.UserDict could be used and should be accepted by the library (UserDict wraps but does not inherit from dict.)

---

:books: Documentation preview :books:: https://python-jsonschema--1027.org.readthedocs.build/en/1027/

Thanks! No worries on the time shortage, I hear you!

Very much appreciate the PR, this is a great plan overall. Will leave some minor comments.

(There's also #1022 from @DanielNoord outstanding to look at, which is driven by typing-related concerns, just in case you haven't seen it).

Nice to see you have found some more time this!

One question though, why did you choose to make the module private? A lot of the typing ends up in the public API as well, so users would then need to import from a private module to make their own annotations be correct.

One question though, why did you choose to make the module private? A lot of the typing ends up in the public API as well, so users would then need to import from a private module to make their own annotations be correct.

I appreciate the question -- and it's a bit of a balancing act, IMO. It depends a great deal on what goes into that module, and how you want to make implementation vs interface decisions.

For example, we have in this PR

_ValidationCallback = typing.Callable[...]

being used in validators.py.

Is that particular type alias a public property of the library? I would say no -- and I think my inclination not to expose that particular type is agreeable to most developers. It's an internal convenience for authors here to be able to write things more clearly and succinctly, just like any other _-prefixed attribute or function in python.

What about _typing.JsonValue or _typing.Schema? That's more debatable. It might eventually be desirable to pull names into jsonschema.typing, so that we can write client code like

validate(typing.cast(jsonschema.typing.JsonValue, my_object))

But that grows the scope of this changeset! Suddenly, I'm not just trying to make some annotations accurate, but I'm also proposing a new public API which jsonschema publishes and maintains! I didn't feel comfortable with that scope creep. I think the question of what types and type aliases, protocols, generics, etc jsonschema publishes should be kept separate from how its own annotations are written.

I hope that makes sense -- and I do intend to get you a good reply on some other threads (notably #1017)! But until I do, thanks for the interest in and contributions towards a well-typed jsonschema! 😸