Overriding annotation/usage keywords at point of use

[handrews]

Use Case and Motivation

This is one of several proposals to come out of the analysis of the "ban additional properties mode" vs $merge/$patch debate and the various use cases that fed into that.

One common use case identified was specifying information about a type's usage at the point of use rather than as part of the initial type definition. In some cases, it is reasonable to provide some generic usage information in the type definition which serves as default usage documentation, but needs to be overridden in some uses with more specific information.

Additionally, default cannot meaningfully appear in multiple branches of logical keywords such as allOf, as there is no sensible way to choose which value is correct for the specific usage. Conflicting validations in an allOf simply fail the allOf, but conflicting default values are just unusable, independent of validation.

Prior experience

This particular use case has been a major pain point on both large-scale JSON Schema projects with which I have been involved.

One implemented $merge, which was very effective but (as several people have noted, and as I now agree) it is too powerful as it (and $patch) can literally convert any schema into an arbitrarily different schema, or even into a non-schema JSON value. In this project, $merge was used to override default values for default, title, description, and readOnly, or disambiguate among several possible values for those keywords.

The other project ended up redefining many types that should be sharing a definition. In some cases, nearly every schema has had to redefine a particular sub-schema just to change the title and description.

Preserving independent validation

In order to preserve the self-contained nature of validation, usage overriding only applies to the keywords in the "Metadata keywords" section of the validation specification (title, description, and default) plus usage-oriented hyper-schema keywords (readOnly and pathStart).

Breaking self-contained validation has been the main objection to other proposals in this area, either through overly powerful keywords or changing validation modes in ways which are not reflected in the schema itself. This is the only proposal to date that solves this problem with no impact on validation whatsoever.

Existing workarounds

It is possible to use an allOf with a reference to the type schema and a schema that includes only the point-of-use annotations. This is tolerable when reading the schema, but is not good for documentation generation. Each schema within an allOf should be self-contained, which separates the documentation from the thing it's documenting. Additionally, if default annotation fields have been filled out, a documentation tool that attempts to extract and combine annotation data from all allOf branches will just produce conflicting documentation.

Finally, allOf is nonsensical when combining multiple schemas using default, readOnly, or pathStart, as there is no reasonable way to choose which value to use.

The proposal: $use

The keyword $use would be an annotation/hyperschema keyword indicating that a type (via a $ref) is being used with additional annotation and/or hypermedia for this specific use.

$use is an object with two required properties and one optional property; the format for the required properties is borrowed from the $merge and $patch proposals:

• source MUST be a schema, and will nearly always be a $ref as there is no need for $use if you have the literal schema defined in line. Required.
• with should be applied to the resolved source as an application/merge-patch+json instance, which MUST NOT affect any JSON Schema-defined keyword that is not explicitly allowed by the proposal. Required.
  • Non-keyword property names are allowed in order to facilitate JSON Schema extensions that can opt to apply $use to their extensions or not as they choose. Required.

    JSON Merge Patch considerations

Declaring the with object to follow JSON Merge Patch semantics allows implementations to use existing libraries, and frees us up from needing to debate yet another schema combination format.

However, a notable limitation of JSON Merge Patch is that you cannot overwrite something to null, as specifying a null value instead deletes the key entirely. A workaround for this that is consistent with existing JSON Schema behavior is to define null somewhere (perhaps right in the $use object since it does not forbid additional properties) and then $ref it. We would need to declare that $use is processed before $ref. Which is fine because $ref often needs lazy evaluation due to circular references anyway.

Elsewhere, there's been an assertion that $ref must always resolve to a schema. This would require breaking that assumption. Since the assumption was not present in Draft 04 (in which JSON Reference was an entirely separate specification), I think this isn't too unreasonable. A compromise could be that it can reference either a schema or null.

If $ref-ing null doesn't gain acceptance, another option would be an additional keyword in the $use object listing JSON pointers to properties that should be set to null.

"$" in name

I chose $use rather than use on the grounds that keywords that manipulate the schema itself should stand out (I will be filing a more comprehensive issue on the use of $ later as it comes up in yet another not-yet-filed proposal, plus there is an open issue to consider $id in place of id).

Example

{
    "type": "object"
    "properties:" {
        "interestTimestamp": {
            "$use": {
                "source": {"$ref": "#/definitions/specialTimestamp"},
                "with": {
                    "title": "Last Event of Interest",
                    "description": "The last time that something interesting happened.  Cannot be directly updated through the API.",
                    "readOnly": true,
                }
            }
        }
    },
    "definitions": {
        "specialTimestamp": {…}
    }
}

This shows that the type can be concisely defined in a shared location, with a clear usage object applied to it.

Meta-schema considerations

This could be added to the meta-schema by moving most of the keyword definitions into the meta-schema's definitions section grouped by type of keyword, and defining with as a schema minus the forbidden keywords.

[awwright]

Ok, that's right about my "type" example.

But... I'm still trying to think of a reason "allOf" wouldn't suffice.

This example seems perfectly valid to me:

{ allOf: [ {default: []}, {default: null} ] }

If that doesn't really make sense, the problem is probably not yet fully understanding out what "allOf" means (related: #161).

I haven't studied any implementations that use these keywords, are there any specific ones people here use?

[handrews]

I don't think it makes sense, and I don't think it's related to #161 .

If I have that schema, and I want to fill in the default value, do I fill in an empty array or a null? There is no way to tell. $use provides an unambiguous view without making validation any less predictable.

[handrews]

Likewise for title and description. If I'm using title in a display, which title do I use? If I'm generating documentation, I could display all of the descriptions but in my experience (and I have done this particular use case a lot), there's one generic schema that is being re-used, that has a generic description. And then there's a description that is more appropriate for the specific use of that generic schema. And that is the description that needs to get displayed. Showing both is just a confusing mess.

[Relequestual]

I've marked this as a medium priority issue as it would be useful to OPEN API (or whatever it's called today ;) ) and despite my reservations about Swagger, increasing inter-team collaboration is a great thing, and strengthening those relationships is a good thing to do.

I think @tadhgpearson explains the use case fairly well at https://github.com/json-schema-org/json-schema-spec/issues/98#issuecomment-264860961

@awwright do you still have reservations regarding this issue? If so, please can you bullet point them?

@handrews Do you want to copy pasta your first comment and make any alterations based on discussions, then replace the first comment with a link to the new comment? (Only a suggestion, if you think it may help move things along, and push people past the previous discussion to focus on moving this issue forward. I feel it's preferable to opening a new issue. I'm easy).

[handrews]

@Relequestual I'm not sure that dumping that giant first comment on anyone again will really help. But here's a summary:

$use applies an piece of JSON in its with property to the schema in its source property, as if the with JSON is an application/merge-patch+json document.

The difference between $use and $merge is that $use MUST NOT include validation keywords in with.

There is a limitation to application/merge-patch+json that it is not possible to set a property to the value null, as a null in JSON Merge Patch means "remove this property". In practical terms, this is only really an issue for default, as it might be useful to have a default of null. If there's agreement on $use in general we can discuss what, if anything, to do about this limitation.

Here is a snippet of meta-schema that shows source as a full schema and with as a restricted schema. They hyper-schema meta-schema would probably exclude additional keywords, but I'm not going to write that out here.

{
    "definitions": {
        "validationProperties": {
            "enum": ["type", "multipleOf", "maximum", ...]
        },
        "nonValidationSchema": {
            "allOf": [
                {"$ref": "#"},
                {"propertyNames": {"not": {"$ref": "#/definitions/validationProperties"}}}
            ]
        }
    },
    "properties": {
        "$use": {
            "type": "object",
            "properties": {
                "source": {"$ref": "#"},
                "with": {"$ref": "#/definitions/nonValidationSchema"}
            }
        }
    }
}

Note that we do not (and never have) had the ability to say what the target of a $ref must validate against. So if someone were to use a $ref in the with clause (unusual but not unreasonable), the thing referenced must be a nonValidationSchema. This isn't really a new restriction- currently the thing referenced by $ref must be a schema, but we do not have a way to enforce that either. Issue #141 would actually solve this underspecification, btw, if we think it is a concern.

[Relequestual]

OK. I've reviewed this issue and believe we should move forward with it. @handrews Can you see any outstanding issue or things we didn't have consensus on? If not, Tagg this as accepted and available! And then we sit back and watch the PRs roll in... right? =D

[nitmws]

A gentle follow up, @Relequestual : I've checked draft-future and can't find #98 there, and in the schema.json file of the master branch does not show a definition for $use. What progress of this issue may we expect?

[Relequestual]

@nitmws Hey there. Thanks for the prompt. There is some administrative work going on for releasing draft-6 right now. Once that's done, we'll regroup and properly scope for draft-7. Strange this isn't part of the milestone though. It's still tagged and as I suggested the tagging system I'll be sure to use it when scoping.

It would be cool if you could include your usecase or the reason your interested in this issue specifically =] Thanks.

[handrews]

@nitmws the draft-future milestone isn't really well-curated at the moment. As @Relequestual says we'll sort it out once draft-6 is out the door.

And I'll add to the request for your use case, even if it is similar to what is already here. Showing breadth of support helps make the case for adding this.

[ruifortes]

On the topic of "Overriding annotation/usage keywords at point of use" this #98 is getting tremendously overcomplicated and in my 50cent opinion it could not be. Would be nice that before closing #279 which proposes a different approach you could give some feedback why you think that's not a viable solution. I guess that's why it was closed because discussing yet another approach here seams to just increase confusion.

[handrews]

@ruifortes I'm not sure what you mean by "getting tremendously overcomplicated." This issue has seen a lot of discussion due to high levels of interest in both this proposal and in other related ones.

But the proposal itself has remained consistent, aside from a few suggestions on more streamlined syntax. Streamlining the syntax is an easier discussion to have once the approach is agreed upon. Primarily, this issue is about whether to support the annotation-only approach or not. The exact syntax is still open to debate. But preferably only after we decide on the approach. Before that, the questions about syntax are mostly noise as they may end up moot.

If we can agree on the approach, I'd probably want to re-file this in a new issue to focus exclusively on finding the right syntax. Having both discussions simultaneously is confusing.

[epoberezkin]

I actually prefer a more generic $merge to limited annotation only extension.

But even more, I think they should stay outside of spec as a generic JSON extension mechanisms.

[handrews]

@epoberezkin how would a "generic JSON extension mechanism" be indicated in a media type?

[epoberezkin]

application/merge-<anything>+json, e.g. application/merge-schema+json (I assume each subtype needs separate registration, but maybe the whole pattern can be registered?)

Another option is to extend rfc6839, but it's probably not as easy.

I can be wrong but at least the first option seems viable.

[handrews]

I think the pattern would have to involve extending RFC 6839, but just registering a media type that is "schema, but with merges" is doable. Annoying, but doable. Without amending the suffix RFC or something similar, clients can't rely on being able to guess the underlying <anything>+json type based on the pattern, but as long as they recognize the whole thing it's workable.

There's still a great deal of support visible in this issue for including the limited "$use" form, so I'm not giving up on that just yet. You're the one who's all about voting and you're clearly outvoted on this one ;-) But that's not how we're resolving things so this stays open.

[nitmws]

To share my use case:

A JSON Schema may have multiple properties referencing the same subschema object - example:

...
"properties": {
        "uriProperty1": {
            "description": "Local description of the uriProperty1",
            "title": "Local title of uriProperty1",
            "$ref": "#/definitions/aURI"
        },
        "uriProperty2": {
            "description": "Local description of the uriProperty2",
            "title": "Local title of uriProperty2",
            "$ref": "#/definitions/aURI"
        },
...

The referenced subschema may look like that:

...
"definitions": {
        "aURI": {
            "title": "Title of aUri",
            "description": "Description of aURI",
            "type": "string",
            "format": "uri"
        }
...

The current (draft 5) rule for $ref states: All other properties in a "$ref" object MUST be ignored. By that rule it is not possible to apply a local definition to a property referencing a subschema object by $ref, in the example above the title and description of uriProperty1 and uriProperty2 will by ignored and they are replaced by title and definition of the aURI subschema object. The organisation I'm working for, IPTC, and other scenarios require to provide a local definition of the semantics of a property and a local title even if this property references a data structure defined at a generic, global level. The key reason for that need is that it is impossible to write a title and definition for a referenced object covering all the different semantics of properties referencing this object; this leads to a confusion about the semantics. The only practical alternative would be not applying titles and definitions to all involved object but this would downgrade the semantic quality of a schema definition.

Therefore any alternative keyword to $refwhich supports the validity of a local title and description is welcome, the outline of $uselooks promising.

[handrews]

Thanks, @nitmws, this is helpful! Particularly the explanation of why you find yourself in this situation.

[epoberezkin]

@handrews I think if it gets to a vote we need to present people with alternatives in one place and specifically ask for votes rather than for opinions. Comments hardly count for votes as people don't see all the alternatives, they just comment on a specific idea.

But if community prefers $use to $merge I have no problem with that, as long as the choice is clearly presented.

[handrews]

@epoberezkin I am against a vote, as it is explicitly discouraged in IETF process recommendations.

We keep linking to the same proposals over and over again, and this is the only one that continues to attract support. There is strong demand for it and you have not offered a universally supportable alternative (many of us who support this have already registered disapproval of #15), or a compelling reason why this is such a bad thing.

Your main objection seems to be:

I think that the problem of tooling of any kind should NOT be addressed in the standard that has validation as its primary purpose, as otherwise we will be facing feature creep from users of different tools

which is not relevant. These keywords are in the spec, so we need to be able to use them effectively. I have proposed moving them out of validation to another vocabulary- that's #136 . I'm more than happy to work that out first, as I dislike having the annotation keywords in the validation vocabulary myself.

But that's not a problem with this proposal, that's a problem with the existing inclusion of metadata in the validation spec.

[epoberezkin]

Ok, let's wait untill the draft-6 is out, I'll review all this again.

[erayd]

I am against a vote, as it is explicitly discouraged in IETF process recommendations.

Then for what it's worth, I would like to state my preference in favour of $merge. That doesn't necessarily have to be as per #15, but for me inheritance is important, including the ability to to override validation keywords, and $use can't do that.

Regarding the reluctance around including $merge (or indeed other similar functionality) in the JSON schema spec, this feels quite similar to $ref (in that both result in a pre-validation transformation of the schema), and I feel that it should be treated accordingly. If $ref is part of the schema spec, then things like $merge and $use also have a valid claim to be included. If keeping them separate is preferable, then perhaps splitting $ref out of the core and into a separate document that defines preprocessing keywords might be a viable solution, and $merge / $use / etc. can have a logical home there.

Apologies if I'm repeating something that's already been suggested; you guys have written a lot (in many different venues) on this, and I have not read it all.

[epoberezkin]

@erayd if we include anything, I'd rather it be $merge - it solves many real issues, and it covers what $use does as well.

I disagree that $ref can be seen as pre-processing. As I've explained in many places you cannot resolve $refs by including target schemas, it's not equivalent.

$merge ono the other hand, is pre-processing.

[erayd]

I disagree that $ref can be seen as pre-processing. As I've explained in many places you cannot resolve $refs by including target schemas, it's not equivalent.

@epoberezkin Are you referring to #66?

[epoberezkin]

@erayd yes and it's summarised here: https://github.com/json-schema-org/json-schema-spec/issues/279#issuecomment-288558322 and earlier here: https://github.com/json-schema-org/json-schema-spec/issues/98#issuecomment-254064538

[erayd]

@epoberezkin You make good points... having read that, I think I agree with you that $ref isn't preprocessing. Thanks for pointing that out :-).

I would also prefer $merge over $use for standardisation - lacking $merge or something equivalent in the standard, I'll just end up preprocessing things to achieve the same behavior anyway, so IMO it makes sense that the behavior be standardised, as there will be many others in the same boat. Whether that is documented as part of the schema spec or in another document matters less to me than that it be included somewhere.

[handrews]

@erayd the argument against "$merge" is that you cannot reason about the result at all. It allows arbitrary transformations, which is not something that we support and is viewed by many as problematic for validation. Hence treating validation and annotation keywords separately.

[epoberezkin]

I'd like us to step back and review again the list of problems that we want to solve - post draft-6 publication. I was very much hoping that some good idea to additionalProperties problem would come to mind, but only plenty of bad ideas did... Nothing better than $merge so far.

My experience of actually using $merge (I do use it a lot) is that it is easy to reason about it. And that it is difficult to reason about $patch (similar but even more generic idea based on JSON-patch RFC).

Maybe we should require that BOTH parts in $merge should be JSON-schemas and not only source - it is so in all my cases anyway (apart from null case to remove the properties) and I do not see any reason of merging arbitrary JSON into a schema (that's what would make it difficult indeed). That makes it less generic and still as useful. null case is a question, but maybe we should just say that null is equivalent to empty schema (in addition to true)?

[erayd]

@handrews I did read some of those arguments, and there are good points made, but I disagree that arbitrary transformations are a problem, as long as they're predictable and happen prior to using the transformation result for validation (i.e. as a preprocessing step). Is there any lack of clarity that a more detailed specification wouldn't solve?

It's quite possible that I have missed something important though; there is a lot of content, and I haven't seen all of it. Most of what I read has been in this issue, issue #15, and various comments attached to other things.

Maybe we should require that BOTH parts in $merge should be JSON-schemas and not only source...

That seems reasonable, noting that the intended outcome is a valid schema that can be used for validation.

[handrews]

I'd like us to step back and review again the list of problems that we want to solve - post draft-6 publication.

Yeah, that's reasonable.

I was very much hoping that some good idea to additionalProperties problem would come to mind, but only plenty of bad ideas did...

I'm pretty sure there are no good ideas for it. Personally, I don't care, and am strongly against anything that complicates using annotation keywords in an effort to "solve" problems with "additionalProperties" that I don't consider problems (however, that's a personal view, not one that I necessarily expect anyone else to agree with).

If we must "solve" those problems, I want the mechanisms to be separate such that each clearly targets a specific use cases. Overriding metadata is a totally separate problem from "additionalProperties" messes, and the only thing I ever used "$merge" for was overriding metadata. Allowing a validator to completely ignore the effect of "$use" is a very nice property for implementation, and it's much easier to get a large team of engineers to use it in the desired manner.

Maybe we should require that BOTH parts in $merge should be JSON-schemas and not only source

While I'm still against "$merge", that would make it a bit less objectionable. I still think it's a bad idea.

[MikeRalphson]

As requested here, an analysis of additional properties used in combination with $ref over 49,366 OpenAPI (Swagger) 2.0 definitions.

[handrews]

@MikeRalphson thanks for producing this!

To clarify, by "additional properties" you mean additional properties in the {"$ref": "#/some/reference"} object, and not the "additionalProperties" JSON Schema keyword, correct?

For the moment, I'm going to ignore keywords that are neither part of JSON Schema nor have an obvious correlation to proposed or about-to-be-published parts of JSON Schema. I'm also ignoring anything that occurs less than 10 times, to make it a bit more manageable. With that in mind, here are the main takeaways I see:

78436 involve only non-default annotation keywords ("title", "description", "examples", "readOnly"), with "description" by far the most common.

64 involve "default", possibly alongside some of the annotation keywords mentioned above

4239 involve "type", usually alongside some of the above

1182 involve "required", in some cases alongside the above, but mostly on its own

Nothing else has significant numbers- the next most significant is "uniqueItems" at 82.

---

Annotation keywords are overridden more than 10x the times of everything else combined. That, to me, is a pretty compelling argument for "$use" (or an equivalent feature with more concise syntax such as just allowing those keywords alongside "$ref") as its own thing. There is an order of magnitude more demand for this than for keywords that would require "$merge".

As for "type", @MikeRalphson noted elsewhere that in many cases that seems to be adding a type of "object" that was left off of the source, which is possibly a cut-and-paste legacy of some sort. So there is probably not as much real demand for that as their might appear.

Finally, for "required", I think using "$merge" to remove a requirement is a particularly bad use of merging/patching. JSON Schema is a constraint system where constraints are added but never removed. Introducing constraint-removal functionality is one of the main reasons I object to "$merge". In a way that is worse than any complaints about possibly producing an invalid schema. It reverses the entire conceptual model of the system. That's bad.

This data leaves me more convinced than ever that overriding annotation keywords is a feature that we need, and generic merging/patching is a feature that is neither truly needed nor desirable.

[MikeRalphson]

To clarify, by "additional properties" you mean additional properties in the {"$ref": "#/some/reference"} object, and not the "additionalProperties" JSON Schema keyword, correct?

Correct. The confusing column heading comes from the database table used to hold the results.

[tadhgpearson]

Great summary @MikeRalphson! In over 92% of all cases where standard elements accompanied the $ref the author was providing the description. With that in mind, maybe you only need to support overriding the description? Maybe the easiest way to express this is, if there's a description accompanying the $ref, it overrides the description in the referred object?

[handrews]

VOTE-A-RAMA!!!

It's time to gauge community support for all re-use/extension/additionalProperties proposals and actually make some decisions for the next draft.

Please use emoji reactions ON THIS COMMENT to indicate your support.

• You do not need to vote on every proposal
• If you have no opinion, don't vote- that is also useful data
• If you've already commented on this issue, please still vote so we know your current thoughts
• Not all proposals solve exactly the same problem, so we may end up implementing more than one

This is not a binding majority-rule vote, but it will be a very significant input into discussions.

Here are the meanings for the emojis:

• Celebration / Hooray / Tada!: I support this so strongly that I want to be the primary advocate for it
• Heart: I think this is an ideal solution
• Smiley face: I'd be happy with this solution
• Thumbs up: I'd tolerate this solution
• Thumbs down: I'd rather we not do this, but it wouldn't be the end of the world
• Frowny face: I'd be actively unhappy, and may even consider other technologies instead

If you want to explain in more detail, feel free to add another comment, but please also vote on this comment.

The vote should stay open for several weeks- I'll update this comment with specifics once we see how much feedback we are getting and whether any really obvious patterns emerge.

[nitmws]

To clarify my position: only the JSON Schema properties title and description defining the semantics of a property (of my schema) should override title and description of a referenced property. 😍 (= Celebration, as this emoji is not available on Github)

[handrews]

@nitmws for "Celebration" I meant the party streamer cone thing. I'll put it on this comment so you can see and vote with it. I couldn't figure out what else to call it :-P

|----- this thing V

[MikeRalphson]

I believe it's called :tada: -> :tada: (aka "the hooray emoji")

[nitmws]

Ok, my vote: 🎉

[Relequestual]

My experience of actually using $merge (I do use it a lot) is that it is easy to reason about it. And that it is difficult to reason about $patch (similar but even more generic idea based on JSON-patch RFC). - @epoberezkin

Spending some time reviewing #15 , is there any reason we couldn't JUST include $merge but not $pathch? $merge seems easier to understand with minimal effort.

I don't know with other languages, but with perl, this concept is great and I utilise it often.

I see general conversation is that people are worried it may be too complicated and result in people creating things they don't mean to, or are invalid. There's always going to be a gap between new users and power users, and right now, power users want a way to do this. While most seem to be mostly interested in just metadata (which $use would cover), I've still seen more than a handful of people ask for something along the lines of $merge, and not just in github issues.

It's always possible to create nonsensical schemas. We can help by providing examples and common pitfalls on the website if we think it would help.

@epoberezkin Can you speak to difficulty to implement?

@handrews I'm downvoting this because I feel if added to the spec, we will get people asking why $use is limited to non validation key words.

[erayd]

Spending some time reviewing #15 , is there any reason we couldn't JUST include $merge but not $pathch? $merge seems easier to understand with minimal effort.

The null thing, I think. But if it's a choice between having just $merge (without $patch), or neither of them, then I'd far rather have $merge.

[Relequestual]

@erayd I thought the null issue was resolved? https://github.com/json-schema-org/json-schema-spec/issues/15#issuecomment-207262327 (aka, it's not an issue)

@epoberezkin Looks like you were on the same train of thought as me at one point: https://github.com/json-schema-org/json-schema-spec/issues/15#issuecomment-207285175

[handrews]

@Relequestual If we do $merge I'd like $patch as well: it just makes sense to me to support the two well-defined JSON-based patching media types. It's extremely difficult to work with arrays in $merge, for instance. I would assume that in most languages, existing libraries for each media type would be used. I'll comment more in #15

Looking at my comments in #364, my main reason to push for this was "readOnly". I've come around to deciding that my application (Doca) can define its own usage for the other keywords. "default" is a bit problematic, but that's true in many more ways than this one. So if we accept #364 then I actually have no personal need for any of these solutions.

[handrews]

@nitmws , you indicated that you would advocate for this. Various people are pushing hard for "$merge". While I'm not a fan of it, if we went that route would that be acceptable for you? Or do you specifically want to avoid the additional effects of "$merge"?

[erayd]

@Relequestual I think there are still edge cases with null for enum and constant at least, unless I've missed something?

[handrews]

@erayd definitely for const, I think that is the only one. application/merge-patch+json does not work with individual array elements, so enum can contain nulls.

[handrews]

Also, default can be null, and examples.

[tadhgpearson]

I think that some more granularity than the current $ref system is required to prevent massive copy-pasting of fields just to change descriptions. Whether this is directly overriding, $use, or whatever, something is necessary - 🎉

[handrews]

@tadhgpearson all of the discussions (elsewhere) about how "default" can or should be used has made me re-think the description and title use cases from a similar perspective.

These keywords have no impact on validation. So there is no implementation/interoperability concern there.

Really, it is application-defined how these metadata/annotation keywords are used. This is even still true after moving "readOnly" over to that section: neither a validator nor a hyper-client are obligated to do anything about a read-only field. In fact, given the definition of read-only as really meaning "under the control of the source authority", a hyper-client should not assume that sending a changed read-only field in a request is an error- the authority may prefer to just ignore the attempted change.

So what are the interoperability requirements for these keywords? They are application-specific. We may want to guarantee behavior in an API Documentation context, but that would be better handled in the specification for that vocabulary. That could specify, for instance, that descriptions are concatenated with two newlines between each for display. Or that a description in a parent schema replaces all in child schemas for the purpose of displaying the parent schema.

UI generation would have similar but perhaps not identical requirements.

And many applications just won't care.

Increasingly, I don't see a need to define combinatoric behavior for the metadata/annotation keywords within the validation or core specification. Application (or application domain)-specific vocabularies would be better places to nail down common behavior.

So for those of us who do not want to allow merging/patching on arbitrary keywords, there's not actually anything that needs to be done. Except maybe opening an issue on the API Doc vocabulary at https://github.com/json-schema-org/json-schema-vocabularies/issues/new

[nitmws]

Re https://github.com/json-schema-org/json-schema-spec/issues/98#issuecomment-326424661 : hm, I would have to dig into all the issues regarding $match first ... Currently my available time is limited.

[handrews]

@nitmws current discussions with @Relequestual and others are leaning towards punting all of this out of draft-07 (to get it wrapped up in the next month) and making it the primary focus of draft-08 (which would be published as soon as we have a resolution, possibly much sooner than 6 months after draft-07). When we've decided one way or another I'll update all the issues. Some will get closed as non-viable, while others will probably get consolidated into a few issues summarizing these epic discussions. No one wants to read 100 comments, many of which go in circles anyway :-P