JSON Schema
Schema references with $ref - Difference between Draft 5 and Draft 6 #526
Replies: 6 comments 7 replies
-
|
There was no intended behavior change for references between these drafts. I personally believe the previous wording was better and draft-04 was even better in that it just referenced a separate and reusable JSON Reference spec. It was around the time draft-05/6 were being worked on that the idea of JSON Reference being a generic re-usable thing was abandoned and started transitioning into a JSON Schema specific concept. I think that's unfortunate. People started to think about references as a special case of a schema rather than a separate concept. That's where the language change comes from. Personally, I still prefer to think of a reference as not a schema. I don't even consider it an object. It's a representation of a "reference" that happens to have similar syntax to an object. |
Beta Was this translation helpful? Give feedback.
-
|
Hi @jdesrosiers, Thanks for clarifying. Though I still have couple of questions to ask to help me fully understand the intentions ;]
This would mean that in all prior drafts to Draft 2019-09, whenever we see JSON Schema Example of {
"type": "object",
"properties": {
"prop1": { "$ref": "https://exmaple.com/schema.json" }
}
}Symbolic expression representation In Draft 2019-09, whenever we see This understanding would contrast with your explanation (mentioned below) but I assume you were referring to draft prior to Draft 2019-09.
JSON Schema Example {
"type": "object",
"properties": {
"prop1": { "$ref": "https://exmaple.com/schema.json" }
}
}Symbolic expression representation |
Beta Was this translation helpful? Give feedback.
-
Technically, no, but effectively, yes. Since draft-05, the spec doesn't reference the JSON Reference spec anymore. That spec was merged into the JSON Schema spec. In that merge, nothing changed other than that it wasn't called a "JSON Reference" anymore. That remained the case until 2019-09. Since the behavior didn't change, you can still think of it as complying with the JSON Reference spec even though that's not technically what the spec says. It works because the JSON Reference spec and the JSON Schema spec never disagree.
Correct.
Yes, additional keywords can be used alongside The way I think about it is that the representation of a JSON Reference has changed from an object ( If it helps, I like to imagine references using a made up syntax to remind that a reference is not a normal JSON type. draft-04/6/7 {
"type": "object",
"properties": {
"prop1": < "$ref": "https://exmaple.com/schema.json" >
}
}2029-09,2020-12 {
"type": "object",
"properties": {
"prop1": { "$ref": <https://exmaple.com/schema.json> }
}
} |
Beta Was this translation helpful? Give feedback.
-
|
@jdesrosiers thanks for all the clarifications. SummaryJust to sum it all up for me and others... As you've already mentioned before:
... and even though Draft 6 and Draft 7 started to talk about
So in the light of that and all your clarifications, the following is true JSON Schema Draft 4/5/6/7 {
"type": "object",
"properties": {
"prop1": { "$ref": "https://exmaple.com/schema.json" }
}
}Symbolic expression representation: >= JSON Schema Draft 2019-09 {
"type": "object",
"properties": {
"prop1": { "$ref": "https://exmaple.com/schema.json" }
}
}Symbolic expression representation:
|
Beta Was this translation helpful? Give feedback.
-
|
I' would also like to clarify on the following:
Our implementation is currently guided with https://json-schema.org/draft/2020-12/draft-bhutton-json-schema-00#rfc.section.7.7.1.1 Which means that our dereferencing (reference removal) works like simple shallow right merge (definition authors and implementation aggreed on this): Input JSON Schema: {
"title": "Feature list",
"type": "array",
"prefixItems": [
{
"title": "Feature A",
"properties": {
"enabled": {
"$ref": "#/$defs/enabledToggle",
"default": true
}
}
},
{
"title": "Feature B",
"properties": {
"enabled": {
"description": "Feature B description",
"$ref": "#/$defs/enabledToggle"
}
}
}
],
"$defs": {
"enabledToggle": {
"title": "Enabled",
"description": "generic description",
"type": ["boolean", "null"],
"default": null
}
}
}Dereferenced JSON Schema: {
"title": "Feature list",
"type": "array",
"prefixItems": [
{
"title": "Feature A",
"properties": {
"enabled": {
"title": "Enabled",
"description": "generic description",
"type": ["boolean", "null"],
"default": true
}
}
},
{
"title": "Feature B",
"properties": {
"enabled": {
"title": "Enabled",
"description": "Feature B description",
"type": ["boolean", "null"],
"default": null
}
}
}
],
"$defs": {
"enabledToggle": {
"title": "Enabled",
"description": "generic description",
"type": ["boolean", "null"],
"default": null
}
}
}@jdesrosiers would you please describe on my example how the result of dereferencing in context of your clarification would look like? Thanks a lot! |
Beta Was this translation helpful? Give feedback.
-
|
Removal of all references is not something supported by JSON Schema. There are some cases where it's not possible, and many cases where it will result in a change of behaviour and validation result. Why do you want to remove all references? Is it due to downstream tooling? Any tooling that requires removal of references is unable to fully support JSON Schema 2019-09 or above. |
Beta Was this translation helpful? Give feedback.
-
|
As Ben said, it's not recommended to dereference a schema this way, but if you insist, you'd have to use the "enabled": {
"allOf": [{
"title": "Enabled",
"description": "generic description",
"type": ["boolean", "null"],
"default": null
}],
"description": "Feature B description",
}
That section isn't intended to allow implementations to merge schemas. It's about interpreting annotation results. The annotation results for the example above includes two Here's an example of where your merging strategy would produce incorrect results. {
"type": "number",
"$ref": "#/$defs/string",
"$defs": {
"string": { "type": "string" }
}If merged, the If the only keywords that conflict are annotations and your implementation only needs to use annotations in one particular way, then there's no harm in merging the way you have. It's not technically correct, but the end result is the same. However, you'll need to check to ensure that keywords that aren't annotations never get merged that way. Maybe you could merge annotations, but use the However, keep in mind that using reference merging as your sole means of disambiguating multiple annotations wouldn't be sufficient. You can have multiple annotations from a completely dereferenced schema. Take the schema above for example. It has no references, yet there are two |
Beta Was this translation helpful? Give feedback.
-
|
Hi @Relequestual, thanks for the reactin.
Yes, I'm aware of this, I've carefully read the https://json-schema.org/draft/2019-09/draft-handrews-json-schema-02#rfc.appendix.B.2. I'm not using dereferenced JSON Schema for later validation, but for other purposes like rendering, data generation, and others...where the representation is only approximation of the original intention not 100% reflection of it. Let's say for the sake of the argument that I want to dereference the JSON Schema mentioned in https://github.com/orgs/json-schema-org/discussions/526#discussioncomment-7563198 (assuming it's Draft 2019-09 or 2020-12). I couldn't find one example of the dereferenced structure within the docs that would demonstrate how to do it, just the section (https://json-schema.org/draft/2020-12/draft-bhutton-json-schema-00#rfc.section.7.7.1.1) that describes the result of dereferencing in words and then the reference of @jdesrosiers where he is mentioning the I'm currently assuming that it would look like this: Dereference JSON Schema: {
"title": "Feature list",
"type": "array",
"prefixItems": [
{
"title": "Feature A",
"properties": {
"enabled": {
"allOf": [
{
"title": "Enabled",
"description": "generic description",
"type": ["boolean", "null"],
"default": null
},
{ "default": true }
]
}
}
},
{
"title": "Feature B",
"properties": {
"enabled": {
"allOf": [
{
"title": "Enabled",
"description": "generic description",
"type": ["boolean", "null"],
"default": null
},
{ "description": "Feature B description" }
]
}
}
}
],
"$defs": {
"enabledToggle": {
"title": "Enabled",
"description": "generic description",
"type": ["boolean", "null"],
"default": null
}
}
}Is my assumption correct? |
Beta Was this translation helpful? Give feedback.
-
There exists data generation tooling that works with references. We should upgrade any tooling that doesn't support references, to support references. There is ongoing work to create libraries which handle all of the complexities so you don't have to.
This is because our recommendation is to not do this. In the case of dyanmic references, it may not be even possible.
Yes. But as mentioned, this will not always be possible. Cyclical references can't be fully removed, and in some cases dynamic references do not know the resolution location till runtime. As an aside, we really appreciate you being interested and asking questions in our community. Keep it up =] |
Beta Was this translation helpful? Give feedback.
-
|
Hi @Relequestual and @jdesrosiers. @jdesrosiers confirmed that the theoretical reference removal will have following form: "enabled": {
"allOf": [{
"title": "Enabled",
"description": "generic description",
"type": ["boolean", "null"],
"default": null
}],
"description": "Feature B description",
}I assumed in this comment that it will have the following form and @Relequestual confirmed it: "enabled": {
"allOf": [
{
"title": "Enabled",
"description": "generic description",
"type": ["boolean", "null"],
"default": null
},
{
"description": "Feature B description"
}
]
}In terms of validation, both schema objects will behave similarly (more like equivalently?), as they both ultimately set Which one would be more correct form? Can we agree on one form? |
Beta Was this translation helpful? Give feedback.
-
|
In the simplest use case, the approach I showed would work, but not in all situations, hence @jdesrosiers's. Consider the following two schemas, followed by a "dereferenced" version. {
"properties": {
"foo": true,
"bar": true
},
"$ref": "/schemaB.json",
"unevaluatedProperties": false
}{
"$id": "/schemaB.json",
"properties": {
"baz": true
}
}{
"allOf": [
{
"properties": {
"foo": true,
"bar": true
},
"unevaluatedProperties": false
},
{
"properties": {
"baz": true
}
}
]
}{
"foo": 1,
"bar": 2,
"baz": 3
}By the time you try to work out and cater for all the possible edge cases, it might have been simpler to just support processing references! |
Beta Was this translation helpful? Give feedback.
-
@Relequestual's excellent explanation shows why the singleton |
Beta Was this translation helpful? Give feedback.
-
|
Thanks both of you for patiently answering my question. Really appreciate it. |
Beta Was this translation helpful? Give feedback.
-
Hi everybody,
I'm seeking clarity between
Schema references with $ref.For Draft 5 the definition is as follows:
For Draft 6 the definition is as follows:
From Draft 5 I can clearly infer that
{ $ref: <URI> }is not a schema object, but rather just an object with a$refproperty - similar with semantics to the object defined forpropertieskeyword.From Draft 6 I would infer that
{ $ref <URI> }is a schema object with a$refkeyword. Also in Draft 6 I don't understand the following sentence:An object schema with a "$ref" property MUST be interpreted as a "$ref" reference, but again I assume it tries to clarify that the object with a$refkeyword is a schema object.Would the authors please clarify the difference?
Beta Was this translation helpful? Give feedback.
All reactions