From 3e55305bcdeb78d321078d0ec720d4a518a67d89 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Sat, 24 Aug 2019 22:54:41 -0700 Subject: [PATCH 1/4] Generative use case guidance This is going to be a powerful technique for generative use cases, which have been observed either requiring references (as opposed to subschemas) in certain places, or implementing various sorts of inferencing around references on their own or in conjunction with other keywords. For example, one OpenAPI documentation tool assumes that in an "allOf" of several references, the first is a base class of some sort. While this is not correct behavior by either JSON Schema or OpenAPI, it demonstrates a feature built by making implicit assumptions about certain references. This section provides a recommendation for making such behavior explicit, and also guides writers of such tools to the concept of extension vocabularies and annotations. --- jsonschema-core.xml | 62 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 41610a2a..a7ac3fa3 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -3589,6 +3589,68 @@ User-Agent: product-name/5.4.1 so-cool-json-schema/1.0.2 curl/7.43.0 +
+ + While the presence of references is expected to be transparent + to validation results, generative use cases such as code generators + and UI renderers often consider references to be semantically significant. + + + To make such use case-specific semantics explicit, the best practice + is to create an annotation keyword can be created for use in the same + schema object alongside of a reference keyword such as "$ref". + +
+ + For example, here is a hypothetical keyword for determining + whether a code generator should consider the reference + target to be a distinct class, and how those classes are related. + Note that this example is solely for illustrative purposes, and is + not intended to propose a functional code generation keyword. + + + + +
+ + Here, this schema represents some sort of object-oriented class. + The first reference in the "allOf" is noted as the base class. + The second is not assigned a class relationship, meaning that the + code generator should combine the target's definition with this + one as if no reference were involved. + + + Looking at the properties, "foo" is flagged as object composition, + while the "date" property is not. It is simply a field with + sub-fields, rather than an instance of a distinct class. + + + This style of usage requires the annotation to be in the same object + as the reference, which must be recognizable as a reference. + +
+
Thanks to From 368d88f702b60658957aace01da9611eab28dca9 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Wed, 4 Sep 2019 20:04:09 -0700 Subject: [PATCH 2/4] Fix munged sentence based on PR feedback --- jsonschema-core.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index a7ac3fa3..6903b8aa 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -3597,7 +3597,7 @@ User-Agent: product-name/5.4.1 so-cool-json-schema/1.0.2 curl/7.43.0 To make such use case-specific semantics explicit, the best practice - is to create an annotation keyword can be created for use in the same + is to create an annotation keyword for use in the same schema object alongside of a reference keyword such as "$ref".
From 1f2aae4c3d8fbecf55192ebad2381fd6bfd83012 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Sat, 24 Aug 2019 22:32:20 -0700 Subject: [PATCH 3/4] Add guidance on bundling and references This should make clear what use cases are considered valid and safe, vs when someone is on their own in terms of figuring that out. --- jsonschema-core.xml | 51 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 6903b8aa..41012812 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -3414,6 +3414,57 @@ User-Agent: product-name/5.4.1 so-cool-json-schema/1.0.2 curl/7.43.0
+
+ + Various tools have been created to rearrange schema documents + based on how and where references ("$ref") appear. This appendix discusses + which use cases and actions are compliant with this specification. + +
+ + A set of schema resources intended for use together can be organized + with each in its own schema document, all in the same schema document, + or any granularity of document grouping in between. + + + Numerous tools exist to perform various sorts of reference removal. + A common case of this is producing a single file where all references + can be resolved within that file. This is typically done to simplify + distribution, or to simplify coding so that various invocations + of JSON Schema libraries do not have to keep track of and load + a large number of resources. + + + This transformation can be safely and reversibly done as long as + all static references (e.g. "$ref") use URI-references that resolve + to canonical URIs, and all schema resources have an absolute-URI + as the "$id" in their root schema. + + + With these conditions met, each external resource can be copied + under "$defs", without breaking any references among the resources' + schema objects, and without changing any aspect of validation or + annotation results. The names of the schemas under "$defs" do + not affect behavior, assuming they are each unique, as they + do not appear in canonical URIs for the embedded resources. + +
+
+ + Attempting to remove all references and produce a single schema document does not, + in all cases, produce a schema with identical behavior to the original form. + + + Since "$ref" is now treated like any other keyword, with other keywords allowed + in the same schema objects, fully supporting non-recursive "$ref" removal in + all cases can require relatively complex schema manipulations. It is beyond + the scope of this specification to determine or provide a set of safe "$ref" + removal transformations, as they depend not only on the schema structure + but also on the intende usage. + +
+
+
From 176fdbab00b7c1cec887cbff087c890154839d9f Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Mon, 26 Aug 2019 10:39:18 -0700 Subject: [PATCH 4/4] Fix type from review feedback Co-Authored-By: Phil Sturgeon --- jsonschema-core.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 41012812..5ad0b18a 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -3460,7 +3460,7 @@ User-Agent: product-name/5.4.1 so-cool-json-schema/1.0.2 curl/7.43.0 all cases can require relatively complex schema manipulations. It is beyond the scope of this specification to determine or provide a set of safe "$ref" removal transformations, as they depend not only on the schema structure - but also on the intende usage. + but also on the intended usage.