add bundling docs

Author: gregsdennis

.jekyll-metadata

@@ -497,70 +497,15 @@ In order to support scenarios where schemas cannot be registered ahead of time,
 
 The URI that is passed may need to be transformed, based on the schemas you're dealing with.  For instance if you're loading schemas from a local filesystem, and the schema `$ref`s use relative paths, you may need to prepend the working folder to the URI in order to locate it.
 
-<!-- ## Bundling
+## Bundling schemas {#schema-bundling}
 
-JSON Schema can be bundled so that they include all of their referenced documents.  This process can make sharing schemas significantly easier as only a single file need to be shared.
+When you need to distribute a schema and all of its referenced documents as a single file, use schema bundling.
 
-This library bundles schemas by collecting all of the referenced documents along with the root schema into a new schema's `$defs` keyword, then adding a `$ref` to the definition for the root schema.
+The dedicated [Bundling](/schema/bundling) page explains:
 
-For example, given this root and external schema:
-
-```jsonc
-// root
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://json-everything.net/foo",
-  "type": "object",
-  "properties": {
-    "bar": {
-      "$ref": "bar"
-    }
-  }
-}
-
-// external
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://json-everything.net/bar",
-  "type": "string"
-}
-```
-
-calling `schema.Bundle()`
-
-```c#
-var bundled = rootSchema.Bundle();
-```
-
-generates the following bundled schema:
-
-```json
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://json-everything.net/foo(bundled)",
-  "$defs": {
-    "26f6f0d167": {
-      "$schema": "https://json-schema.org/draft/2020-12/schema",
-      "$id": "https://json-everything.net/foo",
-      "type": "object",
-      "properties": {
-        "bar": {
-          "$ref": "bar"
-        }
-      }
-    },
-    "c6e748adb1": {
-      "$schema": "https://json-schema.org/draft/2020-12/schema",
-      "$id": "https://json-everything.net/bar",
-      "type": "string"
-    }
-  },
-  "$ref": "https://json-everything.net/foo"
-}
-```
-
-> This process requires that all external documents are registered or automatic resolution be enabled.
-{: .prompt-info } -->
+- how `SchemaRegistry.CreateBundle()` structures bundled output
+- which reference types are supported
+- setup requirements and a full example
 
 # Customizing error messages {#schema-errors}
 

_docs/schema/basics.md

@@ -0,0 +1,109 @@
+---
+layout: page
+title: Bundling JSON Schemas
+bookmark: Bundling
+permalink: /schema/:title/
+icon: fas fa-tag
+order: "01.015"
+---
+Bundling creates a single schema document that contains a root schema and all schemas it references.  This is useful when sharing schemas with other teams or shipping self-contained validation assets.
+
+In _JsonSchema.Net_, bundling is performed by `SchemaRegistry.CreateBundle()`.
+
+## How bundling works
+
+`CreateBundle(rootUri, bundleUri, options)` will create a new Draft 2020-12 schema that:
+
+- sets `$id` to `bundleUri`
+- sets top-level `$ref` to `rootUri`
+- adds a `$defs` keyword for the root schema as well as any schemas it references
+
+The keys in `$defs` are the resolved reference URIs as strings.
+
+The process traverses only standard `$ref` references.  Dynamic and recursive references (`$dynamicRef`, `$recursiveRef`) are not supported for bundling and will throw `NotSupportedException`.
+
+If a referenced document cannot be resolved, `RefResolutionException` is thrown.
+
+If `rootUri` cannot be found in the registry, the method returns `null`.
+
+## Prerequisites
+
+Before bundling:
+
+- ensure the root schema is available in a `SchemaRegistry`
+- ensure all referenced schemas are either:
+  - pre-registered in that registry, or
+  - resolvable via `SchemaRegistry.Fetch`
+
+> Bundling does not infer schemas from arbitrary files.  References must resolve through the registry.
+{: .prompt-info }
+
+## Basic example
+
+```c#
+_ = JsonSchema.FromText(
+    """
+    {
+      "$schema": "https://json-schema.org/draft/2020-12/schema",
+      "$id": "https://schemas.example.com/person",
+      "type": "object",
+      "properties": {
+        "address": { "$ref": "https://schemas.example.com/address" }
+      }
+    }
+    """);
+
+_ = JsonSchema.FromText(
+    """
+    {
+      "$schema": "https://json-schema.org/draft/2020-12/schema",
+      "$id": "https://schemas.example.com/address",
+      "type": "object",
+      "properties": {
+        "street": { "type": "string" },
+        "postalCode": { "type": "string" }
+      },
+      "required": ["street", "postalCode"]
+    }
+    """);
+
+var bundled = SchemaRegistry.Global.CreateBundle(
+    new Uri("https://schemas.example.com/person"),
+    new Uri("https://schemas.example.com/person.bundle")
+);
+
+if (bundled is null)
+    throw new InvalidOperationException("Root schema was not found.");
+```
+
+The resulting bundle will have this shape:
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.example.com/person.bundle",
+  "$ref": "https://schemas.example.com/person",
+  "$defs": {
+    "https://schemas.example.com/person": { "...": "root schema" },
+    "https://schemas.example.com/address": { "...": "referenced schema" }
+  }
+}
+```
+
+## Build options
+
+You can pass a `BuildOptions` instance as the third parameter when creating the bundle.
+
+If `options` is omitted, `CreateBundle()` will use the global registry.
+
+Use custom options when you need specific build behavior (for example, custom dialect/registry settings used by your environment).
+
+## When to use bundling
+
+Bundling is a good fit when:
+
+- consumers need a single document instead of a graph of remote references
+- deployment environments have restricted network access
+- schema artifacts are versioned and distributed as build outputs
+
+For interactive or frequently changing schema graphs, keeping references external can still be a better operational model.