Merge pull request #392 from gregsdennis/schemadata/examples

add examples for schema data usage; actually use external data registry

Author: gregsdennis

JsonSchema.Data/DataKeyword.cs

@@ -45,8 +45,10 @@ public class DataKeyword : IJsonSchemaKeyword, IEquatable<DataKeyword>
 	/// This property stores full JSON documents retrievable by URI.  If the desired
 	/// value exists as a sub-value of a document, a JSON Pointer URI fragment identifier
 	/// should be used in the `data` keyword do identify the exact value location.
+	///
+	/// This registry will be checked before attempting to fetch the data.
 	/// </remarks>
-	public static ConcurrentDictionary<Uri, JsonValue?> ExternalDataRegistry { get; } = new();
+	public static ConcurrentDictionary<Uri, JsonNode> ExternalDataRegistry { get; } = new();
 
 
 	/// <summary>

JsonSchema.Data/JsonSchema.Data.csproj

@@ -16,7 +16,7 @@
 		<GeneratePackageOnBuild>true</GeneratePackageOnBuild>
 		<DocumentationFile>JsonSchema.Net.Data.xml</DocumentationFile>
 		<LangVersion>latest</LangVersion>
-		<Version>3.1.0-beta2</Version>
+		<Version>3.1.0-beta3</Version>
 		<FileVersion>3.1.0.0</FileVersion>
 		<AssemblyVersion>3.0.0.0</AssemblyVersion>
 		<IncludeSymbols>true</IncludeSymbols>

JsonSchema.Data/UriIdentifier.cs

@@ -74,6 +74,10 @@ public bool TryResolve(EvaluationContext context, out JsonNode? value)
 
 	private static bool Download(Uri uri, out JsonNode? node)
 	{
+		if (DataKeyword.ExternalDataRegistry.TryGetValue(uri, out node))
+			// protect against the off-hand that someone registered a null.
+			return node != null;
+
 		if (DataKeyword.Fetch == null)
 		{
 			node = null;

json-everything.net/Pages/Schema.razor

@@ -61,6 +61,14 @@
 				<RadzenPanelMenuItem Text="Refiners" Value="@("examples/schemagen/refiner")"
 									 Path="@(_pageName + "#" + AnchorRegistry.GetFirstFragment("examples/schemagen/refiner" ))"/>
 			</RadzenPanelMenuItem>
+			<RadzenPanelMenuItem Text="Data Keyword" Expanded="false">
+				<RadzenPanelMenuItem Text="Instance References" Value="@("examples/schemadata/data-ref")"
+									 Path="@(_pageName + "#" + AnchorRegistry.GetFirstFragment("examples/schemadata/data-ref"))"/>
+@*				<RadzenPanelMenuItem Text="Schema References" Value="@("examples/schemadata/schema-ref")"
+									 Path="@(_pageName + "#" + AnchorRegistry.GetFirstFragment("examples/schemadata/schema-ref"))" />
+*@				<RadzenPanelMenuItem Text="Internal References" Value="@("examples/schemadata/external-ref")"
+				                     Path="@(_pageName + "#" + AnchorRegistry.GetFirstFragment("examples/schemadata/external-ref"))"/>
+			</RadzenPanelMenuItem>
 		</RadzenPanelMenuItem>
 		<RadzenPanelMenuItem Text="Release Notes" Icon="format_list_numbered" Expanded="true">
 			<RadzenPanelMenuItem Text="JsonSchema.Net" Value="@("release-notes/json-schema")"

json-everything.net/wwwroot/md/examples/schemadata/data-ref.md

@@ -0,0 +1,89 @@
+Most of the questions that center around referencing data involve comparing the values of properties.  This typically comes in a few flavors:
+
+- How do I require that property `A` is less than property `B`?
+- How do I require that property `A` is one of a list of things specified by property `B`?
+- How do I require that...
+
+## Requiring that `A < B`
+
+We want to specify a minimum for `B` that is the value of `A`.  Unfortunately, JSON Schema doesn't have a mechanism that allows this; it only has `minimum` which must be a static (unchanging) value.  Specifically, as enforced by the meta-schema, `minimum` must be a number.
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "A": { "type": "number" },
+    "B": {
+      "type": "number",
+      "minimum": ???
+    }
+  }
+}
+```
+
+We can't put a number here because we want that value to depend on the value of `A`.
+
+To solve this, we remove the `minimum` keyword and add the `data` keyword.  Inside `data`, we specify `minimum` with a plain JSON Pointer (_not_ URI-encoded) that points to where in the instance we want to get the value; in this case, from the `A` property.
+
+```json
+{
+  "$schema": "https://json-everything.net/meta/data-2022",
+  "type": "object",
+  "properties": {
+    "A": { "type": "number" },
+    "B": {
+      "type": "number",
+      "data": {
+        "minimum": "/A"
+      }
+    }
+  }
+}
+```
+
+| Passes | Fails |
+| :-: | :-: |
+| `{ "A": 5, "B": 10 }` | `{ "A": 15, "B": 10 }` |
+
+## Requiring that `A` is one of the items in `B`
+
+We want to specify an enum for `A`, and the values in that enum are contained in `B`.  Similarly to the numbers problem above, JSON Schema only allows for explicit lists for `enum`, so we can't source it from somewhere else.
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "A": { "enum": [ ??? ] },
+    "B": {
+      "type": "array",
+      "items": { "type": "string" }
+    }
+  }
+}
+```
+
+We know that `B` must be an array of strings, but how do we define that `A` has to be one of the strings defined in `B`?
+
+Again, we need to define the keyword that needs the reference (`enum`) inside a `data` keyword and provide a plain JSON Pointer that points to where in the instance we want to get the values; in this case from the `B` property.
+
+```json
+{
+  "$schema": "https://json-everything.net/meta/data-2022",
+  "type": "object",
+  "properties": {
+    "A": {
+      "data": {
+        "enum": "/B"
+      }
+    },
+    "B": {
+      "type": "array",
+      "items": { "type": "string" }
+    }
+  }
+}
+```
+
+| Passes | Fails |
+| :-: | :-: |
+| `{ "A": "cat", "B": [ "dog", "cat", "gerbil" ] }` | `{ "A": "giraffe", "B": [ "dog", "cat", "gerbil" ] }` |

json-everything.net/wwwroot/md/examples/schemadata/external-ref.md

@@ -0,0 +1,63 @@
+Sometimes the values you want to use for schemas are stored in external files.  To reference these, you'll need to use a URI.  This URI may be combined with a pointer to indicate a location within the file.
+
+## Requiring that `A` is one of the items in _values.json_.
+
+We want to specify an enum for `A`, and the values in that enum are contained in a separate file, _values.json_.  As with the instance data reference case, JSON Schema only allows for explicit lists for `enum`, so we can't source it from somewhere else.
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "A": { "enum": [ ??? ] }
+  }
+}
+```
+
+_values.json_
+```json
+{
+  "values": [ "dog", "cat", "gerbil" ]
+}
+```
+
+How do we define that `A` has to be one of the strings defined in _values.json_?
+
+We need to define the keyword that needs the reference (`enum`) inside a `data` keyword and provide a plain JSON Pointer that points to where in the instance we want to get the values; in this case from the _values.json_ file at `/values`.
+
+```json
+{
+  "$schema": "https://json-everything.net/meta/data-2022",
+  "$id": "https://json-everything.net/example/external-ref",
+  "type": "object",
+  "properties": {
+    "A": {
+      "data": {
+        "enum": "https://data.myserver.com/values.json#/values"
+      }
+    }
+  }
+}
+```
+However, before we can use it, we need to tell the `data` keyword how to find `_values.json`.  There are two ways to do this: registration and fetching.
+
+Registration is the preferred method as it doesn't require that the implementation make any web calls.  The `DataKeyword` class exposes a static `ExternalDataRegistry` property that can house any `JsonNode` data.
+
+```c#
+var valuesText = File.ReadAllText("values.json");
+var values = JsonNode.Parse("valuesText");
+DataKeyword.ExternalDataRegistry["https://data.myserver.com/values.json"] = values;
+```
+
+Fetching the data incurs some security risk as you're calling out to the internet.  To set this up, you'll need to set the `DataKeyword.Fetch` static property to a method that will retrieve your data.  The `DataKeyword.SimpleDownload()` method has been provided for convenience, but it is quite basic.  It supports HTTP/S and `file` protocols.  If you want something more robust or different (e.g. fetching from a database), you'll need to write that method yourself.
+
+```c#
+DataKeyword.Fetch = DataKeyword.SimpleDownload;
+```
+
+The system will always check the registry for a matching URI before attempting to fetch it.
+
+Now we can run it:
+
+| Passes | Fails |
+| :-: | :-: |
+| `{ "A": "cat" }` | `{ "A": "giraffe" }` |

json-everything.net/wwwroot/md/examples/schemadata/schema-ref.md

@@ -1,9 +1,11 @@
-# 3.1.0 (beta 2) ([#326](https://github.com/gregsdennis/json-everything/pull/326) / [#389](https://github.com/gregsdennis/json-everything/pull/389))
+# 3.1.0 (beta 3) ([#326](https://github.com/gregsdennis/json-everything/pull/326) / [#389](https://github.com/gregsdennis/json-everything/pull/389) / [#392](https://github.com/gregsdennis/json-everything/pull/392))
 
 Updated to use JsonSchema.Net v4.
 
 Fixed deserialization bug.
 
+`DataKeyword.ExternalDataRegistry` is actually used.  Previously, checking this registry was skipped (an oversight) before moving on to fetching the data.  Also fixed the type of the property to store `JsonNode` instead of `JsonValue` to support the full range of JSON.
+
 Added `JsonSchemaExtensions.GetData()` to enable easy access to `data` keyword.
 
 # [3.0.1](https://github.com/gregsdennis/json-everything/pull/316)