Release Notes: Dyanmic keywords

Author: jdesrosiers

draft/2020-12/release-notes.md

@@ -102,3 +102,85 @@ Here are some examples to illustrate the changes.
     </td>
   </tr>
 </table>
+
+## $dynamicRef and $dynamicAnchor
+The `$recursiveRef` and `$recursiveAnchor` keywords were replaced by the more
+powerful `$dynamicRef` and `$dynamicAnchor` keywords. `$recursiveRef` and
+`$recursiveAnchor` were introduced in the previous draft to solve the problem of
+extending recursive schemas. As the "recursive" keywords got some use and we
+understood them better, we discovered how we could generalize them to solve even
+more types of problems. The name change reflects that these keywords are useful
+for more than just extending recursive schemas.
+
+A `$dynamicAnchor` can be thought of like a normal `$anchor` except that it can
+be referenced across schemas rather than just in the schema it was defined in.
+You can think of the old `$recursiveAnchor` as working the same way except that
+it only allowed you to create an anchor at the root of the schema and the anchor
+name is always empty.
+
+`$dynamicRef` works the same as the old `$recursiveRef` except that fragments
+are no longer empty (`"$dynamicRef": "#my-anchor"` instead of `"$recursiveRef":
+"#"`) and non-fragment-only URIs are allowed. When a `$dynamicRef` contains a
+non-fragment-only URI-Reference, the schema the URI-Reference resolves to is
+used as the starting point for dynamic resolution.
+
+Here's how you would covert a schema using `$recursiveRef` to use `$dynamicRef`.
+
+<table>
+  <tr>
+    <th>Draft 2019-09</th>
+    <th>Draft 2020-12</th>
+  </tr>
+  <tr>
+    <td><pre>// tree schema, extensible
+{
+  "$schema": "https://json-schema.org/draft/2019-09/schema",
+  "$id": "https://example.com/tree",
+  "$recursiveAnchor": true,
+
+  "type": "object",
+  "properties": {
+    "data": true,
+    "children": {
+      "type": "array",
+      "items": { "$recursiveRef": "#" }
+    }
+  }
+}
+
+// strict-tree schema, guards against misspelled properties
+{
+  "$schema": "https://json-schema.org/draft/2019-09/schema",
+  "$id": "https://example.com/strict-tree",
+  "$recursiveAnchor": true,
+
+  "$ref": "tree",
+  "unevaluatedProperties": false
+}</pre></td>
+    <td><pre>// tree schema, extensible
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://example.com/tree",
+  "$dynamicAnchor": "node",
+
+  "type": "object",
+  "properties": {
+    "data": true,
+    "children": {
+      "type": "array",
+      "items": { "$dynamicRef": "#node" }
+    }
+  }
+}
+
+// strict-tree schema, guards against misspelled properties
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://example.com/strict-tree",
+  "$dynamicAnchor": "node",
+
+  "$ref": "tree",
+  "unevaluatedProperties": false
+}</pre></td>
+  </tr>
+</table>