Clarify "$recursiveAnchor" behavior in terms of base URIs #795
Conversation
jsonschema-core.xml
Outdated
| The value of "$recursiveAnchor" MUST be of type boolean, and | ||
| MUST be true. The value false is reserved for possible future use. | ||
| Note that in the absence of "$recursiveAnchor" (and in some cases | ||
| when it is present", "$recursiveRef"'s behavior is identical to |
There was a problem hiding this comment.
Assuming there should be a closing bracket here?
There was a problem hiding this comment.
Heh, you don't like infinite asides?
jsonschema-core.xml
Outdated
| </t> | ||
| <t> | ||
| If set to true, then when the containing schema object is used | ||
| as a dynamic reference target, a new base URI is determined |
There was a problem hiding this comment.
"as a dynamic reference target (by use of $ref)"
Is this what you mean by that phrase?
There was a problem hiding this comment.
Not quite, but I changed the wording so it should be more clear now.
|
One quick fix. One query. Looking at the example makes the use clear, but I SHOULD be able to mostly understand it without the example. I'm not 100% confident that's the case. I'll re-read a few more times. |
|
I can understand why The example is great BTW! Maybe the spec could detail a step by step algorithm for resolving I'll say it again, the example makes it really clear. I've not looked at this for a while, but looking at the example now, I immediatly understand how it works. Such quick understanding is really encouraging and makes me (and presumidly others) feel smart. 💡 |
There was a problem hiding this comment.
@Relequestual is the current wording an improvement or not? If so, I can work to tweak it more. If not, I'd rather not spend a ton of time improving this new version- we can leave it as it was.
jsonschema-core.xml
Outdated
| The value of "$recursiveAnchor" MUST be of type boolean, and | ||
| MUST be true. The value false is reserved for possible future use. | ||
| Note that in the absence of "$recursiveAnchor" (and in some cases | ||
| when it is present", "$recursiveRef"'s behavior is identical to |
There was a problem hiding this comment.
Heh, you don't like infinite asides?
|
It's a HUGE improvement! Bravo! |
|
@Relequestual I did not add a step-by-step listing (I tried that originally but it got rather hard to do precisely because of too many conditionals). However, I added a paragraph in the intro section before the link to the example that informally summarizes how it works. Does that help? |
This fills in a bit of a conceptual gap, and I think will help folks understand the "$id" / "$anchor" split. It also clarified some thinking on "$recursiveAnchor" for me which will be followed up on in future commits.
This re-casts the behavior of "$recursiveAnchor" in terms of base URIs, and now this whole section is much easier to explain. The examples (or rather, an updated example) will be added in the next commit.
gregsdennis
added
clarification
So.. I know I said I was done, but... I went to add a bit about
$idand$anchorbeing identification keywords (alongside assertions, annotations, applicators, and reserved locations), because it seemed like it might fix a conceptual gap and help folks understand what we're doing with the split, and then I realized that$recursiveAnchorfit into this category if we think about it as dynamically setting the base URI for resolving$recursiveRef. So that's the first commit.This led to a much more straightforward way of explaining how these keywords work, so I reworked that whole section. I feel like with the new presentation, the elaborate justification is not required. That's the second commit (including removing the old example).
The third commit is the new example, explained in terms of the new presentation of how the keywords work. It's down in the Appendixes with the other big example sections.