Merge pull request #713 from handrews/unknown-targets

Note undefined behavior with unknown $ref targets

Author: handrews

jsonschema-core.xml

@@ -1540,6 +1540,41 @@
                     </t>
                 </section>
 
+                <section title="References to Possible Non-Schemas">
+                    <t>
+                        Subschema objects (or booleans) are recognized by their use with known
+                        applicator keywords.  These keywords may be the standard applicators
+                        from this document, or extension keywords from a known vocabulary, or
+                        implementation-specific custom keywords.
+                    </t>
+                    <t>
+                        Multi-level structures of unknown keywords are capable of introducing
+                        nested subschemas, which would be subject to the processing rules for
+                        "$id".  Therefore, having a reference target in such an unrecognized
+                        structure cannot be reliably implemented, and the resulting behavior
+                        is undefined.  Similarly, a reference target under a known keyword,
+                        for which the value is known not to be a schema, results in undefined
+                        behavior in order to avoid burdening implementations with the need
+                        to detect such targets.
+                        <cref>
+                            These scenarios are analogous to fetching a schema over HTTP
+                            but receiving a response with a Content-Type other than
+                            application/schema+json.  An implementation can certainly
+                            try to interpret it as a schema, but the origin server
+                            offered no guarantee that it actually is any such thing.
+                            Therefore, interpreting it as such has security implications
+                            and may produce unpredictable results.
+                        </cref>
+                    </t>
+                    <t>
+                        Note that single-level custom keywords with identical syntax and
+                        semantics to "$defs" do not allow for any intervening "$id" keywords,
+                        and therefore will behave correctly under implementations that attempt
+                        to use any reference target as a schema.  However, this behavior is
+                        implementation-specific and MUST NOT be relied upon for interoperability.
+                    </t>
+                </section>
+
                 <section title="Loading a referenced schema">
                     <t>
                         The use of URIs to identify remote schemas does not necessarily mean anything is downloaded,

jsonschema-validation.xml

@@ -887,8 +887,9 @@
                     </artwork>
                     <postamble>
                         Instances described by this schema should be strings containing HTML, using
-                        whatever character set the JSON string was decoded into (default is
-                        Unicode).
+                        whatever character set the JSON string was decoded into.  Per section 8.1 of
+                        <xref target="RFC8259">RFC 8259</xref>, outside of an entirely closed
+                        system, this MUST be UTF-8.
                     </postamble>
                 </figure>