rules for 'deprecation' annotation confusing, inconsistent

[karenetheridge]

reference: https://json-schema.org/draft/2019-09/json-schema-validation.html#rfc.section.9.3

When the "deprecated" keyword is applied to an item in an array by means of "items", if "items" is a single schema, the deprecation relates to the whole array, while if "items" is an array of schemas, the deprecation relates to the corrosponding item according to the subschemas position.

That this rule doesn't really make any sense:

• what if the 'deprecated' annotation is being applied because of a conditional in the schema? for example:

items:
  if:
    <look for the presence of a particular property/value combination>
  then:
    deprecated: true

And consider an instance where some of the items have the conditional evaluate as true, and some do not. Is it still reasonable to apply the 'deprecated' annotation to all items in the array, when the conditional clearly only applies to some of them?

If, on the other hand, the rule is to be interpreted strictly as "if the schema path ends with "items" and with nothing following, then apply the annotation to the entire array", this rule would not apply, as the schema path for the annotation is ".../items/then/deprecated".

And if that is the case, then this rule should probably also apply to other keywords that apply subschemas to array item instances, namely contains.

(footnote: all of this also needs to be revised to take into account the split of "items" into "items" and prefixItems". But that is an easy search/replace.)

[handrews]

Paging @philsturgeon

[philsturgeon]

This rule aimed to take into consideration the fact that JSON Schema allows items to describe positional items in an array, not all contents of an array. If you have an array where have "foo": [1, "tuesday", false] and you want to deprecate that third item, that's possible.

That is about as far down the rabbit hole of razor edge cases as we chose to go at that point, because as with a lot of JSON Schema, if you want to do something really whacky and confusing, then you absolutely can.

I don't know what should happen with deprecated sat inside an if inside items. Probably the same thing as if you tried to oneOf and deprecate the value of one of those subschemas?

Maybe you could provide an example of the JSON with a comment about which bit you are trying to deprecate, and we can see if there is a simpler way to do it.

[notEthan]

agreeing with @karenetheridge.

why would you not set deprecated on the schema for the array (adjacent to items) when it is intended to apply to the whole array? I don't see how putting it within items make sense for that case.

this has some similarities to the old way required was specified as a boolean keyword of object subschemas. putting required: true or deprecated: true on a child subschema in a way that actually applies to the parent schema isn't consistent with the normal rules of schema application.

I think the spec would be better with that paragraph removed. it's an unnecessary exception to the normal rules of applying annotations, and inconsistent with other similar keywords (e.g. readOnly, which I would expect to apply exactly the same way as deprecated, has no such exception).

[philsturgeon]

@notEthan im not sure what part of what @karenetheridge said you're agreeing with based on the content of your message.

why would you not set deprecated on the schema for the array (adjacent to items) when it is intended to apply to the whole array? I don't see how putting it within items make sense for that case.

Yes if you want to deprecate the array then you should put it adjacent to items. It would only go into the items in array form if you're trying to deprecate one of the positional items in the array.

What you're saying is agreeing with the spec, not what Karen is saying... I think maybe you're looking at a very specific line which talks about an edge case, and thinking its the whole thing?

For context let's all remind ourselves what the spec says about deprecated:

The value of this keyword MUST be a boolean. When multiple occurrences of this keyword are applicable to a single sub-instance, applications SHOULD consider the instance location to be deprecated if any occurrence specifies a true value.

If "deprecated" has a value of boolean true, it indicates that applications SHOULD refrain from usage of the declared property. It MAY mean the property is going to be removed in the future.

A root schema containing "deprecated" with a value of true indicates that the entire resource being described MAY be removed in the future.

When the "deprecated" keyword is applied to an item in an array by means of "items", if "items" is a single schema, the deprecation relates to the whole array, while if "items" is an array of schemas, the deprecation relates to the corrosponding item according to the subschemas position.

Omitting this keyword has the same behavior as a value of false.

The plan with When the "deprecated" keyword is applied to an item in an array by means of "items" was for it to be a guard clause. "If you're gonna do this thing, this is what it means." vs "You need to do this thing."

As for removing it to avoid confusion, sure, I have no problem doing that. I added the explanation for this edge case to the spec at the request of other contributors, but I disagree that its identical to readOnly or writeOnly. You probably don't want to explain that read and write have different positional items in the array, and if you do.... ugh reconsider it. 😆

[notEthan]

I may be getting hung up on the wording "the deprecation relates to the whole array" and reading more into that than intended.
I interpreted this to mean that the annotation value for deprecated of true should apply to the array rather than to each item, which is what I was thinking is inconsistent with how other annotations are applied.

but maybe that is not the intent and "the whole array" is intended to be synonymous with "all the elements of the array".

this is a different point than @karenetheridge has raised about conditional application of subschemas, though related. I was agreeing that the rule for deprecated on an items subschema is confusing or inconsistent, but we were seeing different aspects of that..

[philsturgeon]

It applies to whatever you apply it to.

a) deprecate the whole schema.

type: array
deprecated: true
items:
  type: number

b) deprecate all the contents of the array if you want, but... that's super weird. Knock yourself out.

type: array
items:
  type: number
  deprecated

c) deprecate a tuple in an array

type: array
items:
- type: number
- type: string
- type: string
  enum:
  - Street
  - Avenue
  - Boulevard
- type: string
  deprecated: true
  enum:
  - NW
  - NE
  - SW
  - SE
 

That fourth thing is done, use only the first three things.

If this makes sense then please send PRs. I'd love for evferything to make sense to as many people as possible.

[karenetheridge]

Maybe you could provide an example of the JSON with a comment about which bit you are trying to deprecate, and we can see if there is a simpler way to do it.

I should clarify that I'm speaking with my implementor hat on when I asked this question, not a user -- so I'm trying to figure out how an implementation should handle these various cases.

The plan with When the "deprecated" keyword is applied to an item in an array by means of "items" was for it to be a guard clause. "If you're gonna do this thing, this is what it means." vs "You need to do this thing."

<quote>
When the "deprecated" keyword is applied to an item in an array by means of "items", if "items" is a single schema, the deprecation relates to the whole array, while if "items" is an array of schemas, the deprecation relates to the corrosponding item according to the subschemas position.
</quote>

The part I've bolded [although it's really hard to see with github's new stylesheet changes, sigh] is the part that is inconsistent with normal behaviour. The single schema in the "items" keyword is still applied to each array item individually, and the resulting annotation will be attached to the item(s), not the array itself.

If the intent is not to override normal behaviour but rather to clarify it, then we should definitely remove the paragraph that clarifies the behaviour incorrectly :)

[philsturgeon]

Option A) delete the whole paragraph.

Option B) slightly tweak the paragraph.

When the "deprecated" keyword is applied to an item in an array by means of "items", if "items" is a single schema, the deprecation relates to the whole array every item in the array, while if "items" is an array of schemas, the deprecation relates to the corrosponding item according to the subschemas position.

@handrews @Relequestual as two people I remember joining in on this discussion, what do you two think of this tweak?