From d45ade520091c3edcacdfdf8f1dc38a231f064b6 Mon Sep 17 00:00:00 2001
From: Henry Andrews <andrews_henry@yahoo.com>
Date: Sat, 24 Aug 2019 00:21:19 -0700
Subject: [PATCH] Best practices for adding semantics to references

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 | 61 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 61 insertions(+)

diff --git a/jsonschema-core.xml b/jsonschema-core.xml
index e292e275..a53f84bd 100644
--- a/jsonschema-core.xml
+++ b/jsonschema-core.xml
@@ -2139,6 +2139,67 @@
                             </cref>
                         </t>
                     </section>
+                    <section title="Assigning semantic meaning to references.">
+                        <t>
+                            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 semantically significant.
+                        </t>
+                        <t>
+                            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".
+                        </t>
+                        <figure>
+                            <preamble>
+                                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.
+                            </preamble>
+                            <artwork>
+<![CDATA[
+{
+    "allOf": [
+        {
+            "classRelation": "is-a",
+            "$ref": "classes/base.json"
+        },
+        {
+            "$ref": "fields/common.json"
+        }
+    ],
+    "properties": {
+        "foo": {
+            "classRelation": "has-a",
+            "$ref": "classes/foo.json"
+        },
+        "date": {
+            "$ref": "types/dateStruct.json",
+        }
+    }
+}
+]]>
+                            </artwork>
+                        </figure>
+                        <t>
+                            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.
+                        </t>
+                        <t>
+                            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.
+                        </t>
+                        <t>
+                            This style of usage requires the annotation to be in the same object
+                            as the reference, which must be recognizable as a reference.
+                        </t>
+                    </section>
                 </section>
 
                 <section title='Schema Re-Use With "$defs"' anchor="defs">