From dd3d66c5f7257b2e6da846064a65d99cd924a213 Mon Sep 17 00:00:00 2001
From: Henry Andrews <andrews_henry@yahoo.com>
Date: Tue, 10 Sep 2019 15:01:09 -0700
Subject: [PATCH] Clarify the results of $ref and $recursiveRef

Somewhere along the line, any explicit statement of how these
keywords contribute to schema results got lost.

Put it back in, and add a CREF to ensure that people understand
the implications for keywords adjacent to "$ref".
---
 jsonschema-core.xml | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)

diff --git a/jsonschema-core.xml b/jsonschema-core.xml
index 25b0e605..3f99e8e8 100644
--- a/jsonschema-core.xml
+++ b/jsonschema-core.xml
@@ -1587,7 +1587,14 @@
 
                     <section title='Direct References with "$ref"' anchor="ref">
                         <t>
-                            The "$ref" keyword is used to reference a statically identified schema.
+                            The "$ref" keyword is an applicator that is used to reference a statically
+                            identified schema.  Its results are the results of the referenced schema.
+                            <cref>
+                                Note that this definition of how the results are determined means that
+                                other keywords can appear alongside of "$ref" in the same schema object.
+                            </cref>
+                        </t>
+                        <t>
                             The value of the "$ref" property MUST be a string which is a URI-Reference.
                             Resolved against the current URI base, it produces the URI of the schema
                             to apply.
@@ -1653,6 +1660,10 @@
                                 when it is present), "$recursiveRef"'s behavior is identical to
                                 that of "$ref".
                             </t>
+                            <t>
+                                As with "$ref", the results of this keyword are the results of the
+                                referenced schema.
+                            </t>
                         </section>
                         <section title='Enabling Recursion with "$recursiveAnchor"'>
                             <t>