"Keyword Interactions" section seems ambiguous and inaccurate

[ucarion]

The "Keyword Interactions" section of the core spec currently reads as:

Keyword behavior MAY be defined in terms of the annotation results of
subschemas (Section 4.3.3) and/or adjacent keywords. Such keywords
MUST NOT result in a circular dependency. Keywords MAY modify their
behavior based on the presence or absence of another keyword in the
same schema object (Section 4.3).

It seems to me that the meaning of this paragraph is that:

1. Keyword behavior can only be recursively defined in terms of:
   1. The annotation results of subschemas.
   2. The annotation results of other keywords that share the same parent schema object.
   3. The presence or absence of another keyword in the same schema object.

This definition seems to have a number of problems, on my reading:

1. It leaves unclear whether this section is laying out all a keyword may do, or if it is merely stating what a keyword may not do.
2. Keywords may be defined in terms of the validation results of subschemas and adjacent keywords. The current definition makes no references to validation at all.
3. $ref and $recursiveRef are not supported on this definition. The referent of these keywords may not be in the same schema object, but their outcomes are entirely defined in terms of their referents. Furthermore, $recursiveAnchor affects the behavior of referring schema objects.

As an aside, I don't think the exclusion of circular dependency is required. A circular definition is no definition at all.

I'm happy to open a PR to fix this section! But I would like clarification on the following questions:

1. Are we, in "Keyword Interactions", trying to explicitly lay out everything a keyword may do, or are we merely just enumerating what a keyword shouldn't do?
2. Is the omission of any reference to validation intentional?
3. What does "the same schema object" mean? How does it relate to external references?

Happy to help! But I don't want to make assumptions about the three preceding questions.

[handrews]

Thanks, @ucarion, we're about to enter the final wording / flow review period before publishing the new draft, so we will take care of this during that time (I'll put it in the right milestone). See also #635 and #646. For now please hold off on a PR, as I want to get the last few new features merged first. And then there is some cleanup we know we need to do.

The Overview and Definitions sections have expanded way beyond their original meaning and as you note there are some places where different bits added at different times don't agree with each other. I may ask you to try a PR at some point but let's do a first pass on it to get the right section layout first and see what we have then.

[ucarion]

Understood! Makes sense. I'll consider this issue to be on ice until the finalization phase. :)

[Relequestual]

Regarding "circular dependency"
I think this looks to address a situation where keyword a depends on the assertion result of keyword b, but b depends on the assertion result of keyword a.

With that reading, I'm also not sure we need to include this. Garbage in garbage out. There are plenty of ways to hang yourself writing schemas, so it follows the same is true for writing new vocabularies.

I'm not actually sure this whole section "3.1.1. Keyword Interactions" adds any value.
It, and some of the text in the following section, reads to me like a few hints for vocabulary authors, which has value, but either in it's own section (maybe " 7.4. Best Practices for Vocabulary and Meta-Schema Authors"), or somewhere outside of the spec document.

[Relequestual]

@ucarion FYI it's the finalisation phase / review phase! =]

[Relequestual]

@ucarion There are now 18 days till the end of the 4 week review process.
If you do not respond before then, I'll consider this query defurred till after draft-8.

[ucarion]

Hi @Relequestual,

Where can I find details on this review process? You state that I must "respond" before then, but are there any requirements as to what that response must contain?

[Relequestual]

Sorry I should have said review period. Might have be an autocorrect typo or a brain malfunction. Not sure which.

I don’t think we formally documented our one month review period, but essentially:

Personal drafts mean we could in theory publish whenever we want, but respecting the community that was already behind it when we took it over, and that others who want to be involved don’t have lots of spare time either, we decided that we should give one months notice on our intent to publish a new draft.

We have a contributing document: https://github.com/json-schema-org/json-schema-spec/blob/master/CONTRIBUTING.md

By saying there are 18 days left on the clock, I was inviting you to further discuss this issue within that timeframe so we can try to reach consensus.

I feel the ball is currently on with you, to respond to comments I’ve made above.

You also said you would consider this issue on ice till the finalisation phase. We are now in that phase.

I’m happy to engage and distill discussion on slack, and report back progress and resolution to the issue for tracking, if that might work better.

I didn’t say you must respond, just that if you didn’t, I’d likely defer the issue to the next draft. I meant any kind of response showing intent to further discuss.

You may be under a guise that we are considerably more organised than we actually are. We’re just a few guys trying to make it happen for the community the best we know how with what extra time we can find in our already super busy lives =]

I’m trying to make myself available more moving forward.

We should probably document the one month review period! Feel free to make an issue for that.

[handrews]

@ucarion the process is documented at http://json-schema.org/work-in-progress which was announced and linked to on both the general and draft-publication slack channels.

[handrews]

And is also linked from the json-schema.org front page, for that matter.

[ucarion]

@Relequestual I see -- in that case, I would concur with your sentiment, expressed in this thread, that the entire section of the spec under discussion might not be adding value. I should think we ought to remove what we can, and specify what we must.

In asking for more details, the answer "it's not documented anywhere" is an entirely legitimate answer. :) I phrased it that way mostly to save your time, in case you needed specific requirements from me here.

[handrews]

@ucarion if you want changes, you're going to have to be more specific than that. The immediate goal of publication is to get this out there for larger feedback and handed over to @Relequestual and whoever else in the community (potentially including you!) want to drive the next draft.

For urgent personal reasons I am unable to continue my past levels of involvement, which also means that I am not able to just rewrite a huge swath of things b/c one person vaguely doesn't like it.

In the absence of more focused feedback, more info in the spec is better than less info, and larger adjustments can be made in a follow-on clarification draft (as we did with "draft-07" which got a clarification a couple months after initial publication, with no functional changes).

[Relequestual]

@ucarion Given it sounds like you want to open a discussion on a chunky rewrite of sections, I'm going to consider it out of scope for draft-8 (especially given the late stage), and bump this to draft-9 discussions.

[ucarion]

Yeah, that sounds like a reasonable approach to me. :)