From 1beb14e030899ce71a32fa821131de2d88f8ef61 Mon Sep 17 00:00:00 2001
From: Henry Andrews <henry@cloudflare.com>
Date: Tue, 31 Oct 2017 11:25:47 -0700
Subject: [PATCH 1/3] Clarify what the hrefSchema examples mean.

---
 jsonschema-hyperschema.xml | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml
index 8614d845..7a9fc05c 100644
--- a/jsonschema-hyperschema.xml
+++ b/jsonschema-hyperschema.xml
@@ -1788,7 +1788,8 @@ Link: <https://schema.example.com/entry> rel=describedBy
                 </figure>
                 <t>
                     Notice the "href*" keywords in place of "targetUri".  These are three
-                    possible "targetUri" values covering different sorts of input:
+                    possible kinds of "targetUri" values covering different sorts of input.  Here
+                    are examples of each:
                     <list style="hanging">
                         <t hangText="No additional or changed input:">
                             "mailto:someone@example.com?subject=The%20Awesome%20Thing"

From 66e00462d3e7cfc694bba99022cc09e7022d6042 Mon Sep 17 00:00:00 2001
From: Henry Andrews <henry@cloudflare.com>
Date: Tue, 31 Oct 2017 13:06:32 -0700
Subject: [PATCH 2/3] Use awwright's generic user agent defintion

Because it's much better than what I had there :-)
---
 jsonschema-hyperschema.xml | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml
index 7a9fc05c..d949c398 100644
--- a/jsonschema-hyperschema.xml
+++ b/jsonschema-hyperschema.xml
@@ -182,10 +182,10 @@
                             in the Link Description Object.
                         </t>
                         <t hangText="generic user agent">
-                            A user agent which is only aware of standardized link relations,
-                            media types, URI schemes, and protocols.  It may have an extensible
-                            architecture to allow adding support for standards beyond the core
-                            set of which it is aware.
+                            A user agent which can be used to interact with any resource, from
+                            any server, from among the standardized link relations, media types,
+                            URI schemes, and protocols that it supports; though it may be
+                            extendible to specially handle particular profiles of media types.
                         </t>
                         <t hangText="client application">
                             An application which uses a hypermedia system for a specific

From 8fba21117083b0f8a694f8fea7657765d60b3780 Mon Sep 17 00:00:00 2001
From: Henry Andrews <henry@cloudflare.com>
Date: Tue, 31 Oct 2017 14:51:40 -0700
Subject: [PATCH 3/3] Incorporate awwright's suggestions on cref #1

Better explanation of the concerns around and possible future
direction of $schema usage.

Also add an XML comment to remind us of the most notable concern,
so we can skip the whole thing where we forget about it and then
argue about it until we work it out again.  Which of course has
never happened...
---
 jsonschema-core.xml | 17 ++++++++++++++---
 1 file changed, 14 insertions(+), 3 deletions(-)

diff --git a/jsonschema-core.xml b/jsonschema-core.xml
index 94e38437..f75b45c8 100644
--- a/jsonschema-core.xml
+++ b/jsonschema-core.xml
@@ -436,10 +436,21 @@
             </t>
             <t>
                 <cref>
-                    While this pattern is likely to remain best practice for schema authoring,
-                    implementation behavior is subject to be revised or liberalized in future
-                    drafts.
+                    Using multiple "$schema" keywords in the same document would imply that the
+                    vocabulary and therefore behavior can change within a document.  This would
+                    necessitate resolving a number of implementation concerns that have not yet
+                    been clearly defined.  So, while the pattern of using "$schema" only in root
+                    schemas is likely to remain the best practice for schema authoring,
+                    implementation behavior is subject to be revised or liberalized in
+                    future drafts.
                 </cref>
+                <!--
+                    In particular, the process of validating an instance, including validating a
+                    schema as an instance against its meta-schema, only allows for a single set
+                    of rules across the entire instance document.  There is no equivalent of
+                    changing the meta-schema partway through the validation for non-schema
+                    instances.
+                  -->
             </t>
             <t>
                 Values for this property are defined in other documents and by other parties.