Suggestion: Add docs on $ref resolving

[BlaineAtAffirm]

As seen by issues #132 and #98 , there are some people who have been confused about how to use jsonschema in order to resolve references between schema files. I myself couldn't figure it out until I saw issue #98. I suggest adding some documentation here or perhaps at http://python-jsonschema.readthedocs.org/en/latest/ if it is affiliated.

[Julian]

That's us, yep :).

Docs would definitely be good, there's definitely some missing areas here.

Now that you've figured it out, would you perhaps be willing to write up what you've figured out :)? The docs live in docs/ as .rst files that then get automatically built and uploaded to the ReadTheDocs site you've found.

[BlaineAtAffirm]

Of course I'd be willing to help. That's why I posted :). It will take awhile though (perhaps a week or two week) as I haven't gotten around to learning sphinx or any documentation language. I have been meaning to and this does seem like a good opportunity for it.

[Julian]

Fantastic, thanks so much :).

Feel free to ask any questions, I'd love to help if you get stuck.

[tbielawa]

I'd love to see some action on this. I'd try to tackle it myself but I don't understand the system well enough to do so :(

[jdtangney]

+1

[tbielawa]

@Julian I don't think I could write the comprehensive explanatory details, but would it help if somebody put together some scaffolding? Section headers, sections for examples (with labels) of the common use cases, etc?

[Julian]

Definitely couldn't hurt, if anything someone could pick it up and fill in
some details
On Jul 28, 2014 5:45 PM, "Tim Bielawa" [email protected] wrote:

@Julian https://github.com/Julian I don't think I could write the
comprehensive explanatory details, but would it help if somebody put
together some scaffolding? Section headers, sections for examples (with
labels) of the common use cases, etc?

—
Reply to this email directly or view it on GitHub
#135 (comment).

[BlaineAtAffirm]

Someone could fill in some details here if that's a good start. #172

[samskiter]

@Julian Not sure the most appropriate place to ask, but why do resolvers require a base URI and base document? Why can't I share a resolver across several schemas i might validate?

[samskiter]

Also very +1 for more documentation on refs.

[Julian]

@samskiter they need to know where to look for any relative refs -- what do you mean by share, why can't you just make more of them?

[samskiter]

It's my understanding that the base_uri you pass in will only be useful if all the schemas you use use relative 'id's. As soon as you present a full URI id the base_uri will be overwritten.

And the advantage to sharing the same resolver is sharing its cache.

[samskiter]

As such, it seems that you only need the base_uri if you want to be able to prefix all your relative refs... and the main reason for doing this would be to redirect to a folder. It seems that this job would be better suited to a subclass of RefResolver

[Julian]

It's my understanding that the base_uri you pass in will only be useful if all the schemas you use use relative 'id's. As soon as you present a full URI id the base_uri will be overwritten.

Yeah exactly, but if you have all relative refs, the resolver needs to be able to handle that case, so it needs a base URI.

And the advantage to sharing the same resolver is sharing its cache.

Just do that then :). It's just a dictionary. Pass a bunch of them the same one.

[samskiter]

Yeah exactly, but if you have all relative refs, the resolver needs to be able to handle that case, so it needs a base URI.

This is not the resolvers problem, this would seem to be a schema problem?

Maybe base_uri could be optionally passed into the validate() method instead? That would properly tie the schema to the correct resolution. It is too easy to mess up and pass the wrong schema/uri to the refresolver constructor or your validate() call and then have the Resolver set to the wrong resolution as you call validate.

Just do that then :). It's just a dictionary. Pass a bunch of them the same one.

Revealing implementation a bit there I think ?

[Julian]

Revealing implementation a bit there I think ?

It's explicit in the API that RefResolver takes a (mutable) mapping as a cache, it's not particularly its concern what mapping that is as long as it satisfies that interface.

[Julian]

Although it looks like RefResolver does some more setup these days, which won't break things but which might actually signal that it's time for some more thought there.