What is the referrer argument to RefResolver?

[mdavis-xyz]

What should the referrer argument to RefResolver be?

The documentation just says "The actual referring document". What does that mean? Is that:

• a string of the yaml document
• a dictionary of the yaml document
• a string of the relative file path: ./spec.yaml
• a string of the full file path: /path/to/spec.yaml
• a URI for the file path: file:///path/to/spec.yaml
• any of the above, but for json not yaml
• a pathlib.Path of the file path

The example in the FAQ uses referrer=True. How is True an instance of an actual referring document?

I looked at the code implementing RefResolver. It gets used like if document is self.referrer:. How can that work if referrer is True? I'm confused.

[Julian]

This is going to change in the next version when the referencing library replaces RefResolver.

But it's the actual dictionary it sounds like in your case. In "official" JSON Schema dialects, schema documents are either mappings (dictionaries in Python) or boolean schemas, so in theory a referrer of True is "sensical". The referrer is used for fragments / anchors / JSON Pointers -- e.g. for dereferencing # or #/foo/bar -- a referrer of True would contain no anchors (it contains no properties at all of course) so it should never hit code paths that dereference an anchor within but it's indeed possible to have a schema true be the root document for a ref resolver and to uselessly write # and get back the whole schema or whatever.

But yeah these interfaces are old and not easy to understand, as I say, this should be easier with referencing in the next version (as soon as I finish the work actually deprecating RefResolver, which is the last remaining step).

[mdavis-xyz]

Ok, so what does referrer=False do?

[Julian]

It creates a RefResolver whose schema is the boolean schema false.

[mdavis-xyz]

Are you talking about this?

Sorry I still don't understand. I thought the RefResolver is used to look up something like #/foo/bar from a subset of a schema, and the thing it looks it up from is referrer, as the parent/root schema. True is a schema that marks every possible object as valid. But how does that get used when trying to find True['foo']['bar']? Are you saying that all anchor lookups will fail, because True is really {} which contains no foo member?

[Julian]

Are you talking about this?

Yep exactly!

Are you saying that all anchor lookups will fail, because True is really {} which contains no foo member?

Yes exactly, your understanding is correct it sounds like -- all lookups will fail -- not really because True is {}, that's a "conceptual" equality -- True["foo"] does not exist / is a TypeError in Python / is undefined as a JSON Pointer. That's what I meant by making referrer be those values is "sensical" but not "sensible". And the same for false. Does that help?

[mdavis-xyz]

Yes that helps.

Should I write a PR to clarify the documentation, or is the upcoming change so imminent or substantial that it's not worth bothering?

[Julian]

Great! I'm more than happy to review a PR but the referencing change is happening on this branch -- it's coming along, I expect it to be done in the next 2 weeks or so (and to be in the next release) which will obsolete RefResolver entirely, so it's likely not worth bothering given it probably will never see the light of day anyhow. Feedback will definitely be welcome on the new API though once a beta is released!

[mdavis-xyz]

Ah ok. Never mind then. If someone else has the same question as me in the next two weeks, hopefully they can just find this thread.