Skip to content

add section about keyword interaction mechanics being illustrative #1445

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 9 commits into from
Jun 18, 2024
Merged

add section about keyword interaction mechanics being illustrative #1445

Changes from 8 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
136b55f
add section about annotation-based keyword interaction being illustra…
gregsdennis Sep 20, 2023
7c35719
implementations MAY use their own mechanisms for keyword interaction
gregsdennis Sep 24, 2023
007fa98
add that keywords can be depenedent upon other keywords' values
gregsdennis Sep 26, 2023
130df84
improve language around sibling keyword behavior
gregsdennis Sep 29, 2023
d92e92a
add lanugage to specify where dependent behavior should be defined
gregsdennis Sep 29, 2023
92b7860
define multiple mechanisms
gregsdennis Oct 5, 2023
a7698d4
fix grammatical error
gregsdennis Oct 5, 2023
6caa370
mechanics -> mechanisms
gregsdennis Oct 5, 2023
a5f5782
be consistent with language
gregsdennis Jun 11, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 23 additions & 5 deletions jsonschema-core.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -523,11 +523,29 @@ to inform the user of the evaluation path that produced the error or annotation.

### Keyword Interactions

Keyword behavior MAY be defined in terms of the annotation results of
[subschemas](#root) and/or adjacent keywords (keywords within the same schema
object) and their subschemas. 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](#schema-document).
Unless otherwise specified, keywords act independently.

Keywords MAY modify their behavior based on the presence, absence, or value of
another keyword in the same schema object. Such keywords MUST NOT result in a
circular dependency.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It seems unexpected to have a MUST NOT here about this. It's not wrong, but pretty much all the other MUSTs are either what implementations must do, or what schemas must conform to. This is something another vocabulary or keyword specification must do, so only relevant for a minuscule fraction of readers. Not that it shouldn't be here, but maybe some clarification of the context, what this MUST applies to, would help.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This was already present, I just flipped the sentences because it made more sense to me and felt less redundant this way.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not that it shouldn't be here, but maybe some clarification of the context, what this MUST applies to, would help.

I have a bigger issue with the flow of the document, and I intend to make some bigger changes to the organization. I think this is better saved for when I tackle that.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sounds good, no objection to that.


Supplementary specifications are encouraged to specify any dependencies as part
of the dependent keyword (i.e. the keyword whose behavior is modified).

Within this document, keyword dependencies are expressed using one of the
following mechanisms:

- Static dependencies, in which the dependency relies on the presence or
contents of another keyword.
- Dynamic dependencies, in which the dependency relies on the evaluation of
another keyword against an instance. This dependency may be on either the
annotations produced by the keyword or the validation result of its
subschema(s).

These mechanics are used merely to describe dependencies; they are for
illustrative purposes and not prescriptive. Implementations MAY use whatever
mechanisms make sense given the needs of their architecture and language in
order to achieve the specified behaviors.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure this paragraph is necessary anymore. These are more classifications of behavioral properties than they are mechanisms. They're certainly not implementation details. It seems redundant to state that implementations can implement them however they want because we haven't said anything that constrains how they would implement them. We've only defined their external behaviors.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think it hurts to be explicit here.

The original concern about annotations being the description mechanism was that it would lead implementors into thinking they had to use annotations to drive these dependencies. I don't think the other changes address that concern, but this paragraph does so explicitly.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we keep it, it needs to be made more clear what it's trying to say because I can't make sense of it. The way I understand it, the things you're calling "mechanisms" now are not mechanisms in the same way that annotation are a mechanism. If they were, everything would make sense. Before, we were telling implementations how to get the right outcome using annotations. Now, we're going to tell implementations what the outcome should be and let implementations figure out how to get to that outcome on their own. Since the new way already isn't telling implementations how to get the outcome, it doesn't make sense to me that we're still telling them they can get to that outcome however they need to. We're no longer giving them a "how", so telling them that the "how" is just illustrative doesn't make sense.

I'm sure there's some piece of this that you understand differently that's leading us to different places.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What's unclear about it? We invent some mechanics to describe behavior and then say they're only descriptive and implementations can do what they want as long as the behavior is met.

We're no longer giving them a "how"

We are giving them a "how." It's just the "how" isn't always annotations. Now it can also be "this keyword looks at that keyword."

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The way I understand it, the things you're calling "mechanisms" now are not mechanisms in the same way that annotation are a mechanism.

I disagree. "Dynamic dependencies" even explicitly includes annotations as one of the sub-parts that may be used for determinatioin.

In computer science, a mechanisum is any function that produces an output. We define two classes of mechanisms, but that doesn't negate the fact that there are mechanisms.

Besides, if you take unevaluatedProperties as an example, it still defines using annotations as the mechanism for determining its assertion result.

Before, we were telling implementations how to get the right outcome using annotations.

Aren't we still doing that?

I'm really struggling to reach any other conclusion. Can you help me understand how you reached yours @jdesrosiers?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We are giving them a "how." It's just the "how" isn't always annotations. Now it can also be "this keyword looks at that keyword."

This is the part I'm not following. "This keyword looks at that keyword" doesn't say what mechanism is used to do the looking. That statement describes the behavior, not the mechanism by which the behavior is achieved. It's like saying "Greg goes to the store". The mechanism by which he gets to the store is implicitly up to him. That statement doesn't describe the mechanism he should use to get to the store. He might drive, walk, ride a bike, take a bus, etc.

We're saying that there are two categories of keyword dependencies. One category is where the keyword depends on the value of the dependent keyword. The other category is where where the keyword depends on the value of the dependent keyword as well as an instance. Those are statements of dependency. I don't see how they can be interpreted as mechanisms (or imply a mechanism) for how that dependency is implemented.

Before, we were telling implementations how to get the right outcome using annotations.

Aren't we still doing that?

No, the plan is to undo that except possibly in the case of unevaluated* whose definition is dependent on annotations.

if you take unevaluatedProperties as an example, it still defines using annotations as the mechanism for determining its assertion result.

Right, but that's a different context. This section defines two "mechanisms": static keyword dependencies and dynamic keyword dependencies. Those are the "mechanisms" that are the subject of this passage. Annotations are no longer the subject. Is the point of that passage to say that keywords may describe their behavior in terms of some mechanism, but if they do implementations don't need to use that mechanism? If so, that makes perfect sense. That needs to be said either in this section or by the keyword definition using a mechanism to define behavior. But, that's not what this passage currently says.

I'm really struggling to reach any other conclusion. Can you help me understand how you reached yours @jdesrosiers?

I too am trying very hard to understand this from another perspective. I specifically need help understanding how a statement of dependencies can be interpreted as a mechanism. I've laid out how I have reached by conclusions in this and the previous comments in this thread. I don't know how else to explain it. The only explanation for this misunderstanding is that there is some underlying assumption that we're making differently and not realizing. We are all coming to logical conclusions based on our assumption, but end up with different conclusions because our assumptions are different. I don't know how to tease out that fundamental difference of understanding.

Ultimately, I don't want this to become another big argument. I'm simply trying to understand what that passage is trying to say. The way I understand the passage, it's meaningless, so I'm not concerned about it doing harm. I just want to understand it's intent or remove it if it doesn't make sense.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is the point of that passage to say that keywords may describe their behavior in terms of some mechanism, but if they do implementations don't need to use that mechanism? If so, that makes perfect sense. That needs to be said either in this section or by the keyword definition using a mechanism to define behavior. But, that's not what this passage currently says. - @jdesrosiers

I'm not sure what this passage says to you, but what you described is exactly its purpose: implementations can do what they want so long as the behavior is achieved.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(I did update "mechanics" to "mechanisms" to be consistent with the rest of the section.)


### Default Behaviors {#default-behaviors}

Expand Down