Fully document JSON Schema Draft 7

content/draft7/core/comment.markdown

@@ -10,3 +10,56 @@ metaschema: "http://json-schema.org/draft-07/schema#"
 introduced_in: draft7
 index: -9
 ---
+
+The [`$comment`]({{< ref "draft7/core/comment" >}}) keyword is a
+standardised placeholder for explanatory string schema comments. This
+keyword is completely ignored by the evaluation process and it is possible
+to strip instances of this keyword when distributing your schemas for the
+purpose of space-efficiency. This keyword is commonly used to declare [TODO
+comments](https://en.wikipedia.org/wiki/Comment_%28computer_programming%29#Tags)
+in various parts of a schema.
+
+{{<common-pitfall>}}
+
+Compared to other similar keywords such as [`title`]({{< ref
+"draft7/validation/title" >}}) and [`description`]({{< ref
+"draft7/validation/description" >}}), this keyword does not produce any
+semantic meaning. Furthermore, the specification explicitly prohibits any JSON
+Schema tooling from inferring meaning from this keyword or elevating its
+contents to the end user in any way.
+
+{{</common-pitfall>}}
+
+{{<learning-more>}}
+
+The JSON data format does not support any form of comments at the grammar
+level. While this is a common point of contention, comment support (or any
+other improvement) will be never added. The [ECMA
+404](https://ecma-international.org/publications-and-standards/standards/ecma-404/)
+JSON standard declares that: *"it is not expected that the JSON grammar will
+ever change"*. If this keyword is not enough, there are various other data
+formats that operate on the JSON data model that have comment support, like
+[YAML](https://yaml.org) and [JSON5](https://json5.org).  However, JSON remains
+by far the preferred data format within the community, both when authoring
+schemas and over the wire.
+
+{{</learning-more>}}
+
+## Examples
+
+{{<schema `A schema that declares a top level and a nested comment`>}}
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$comment": "This is an internal note about the schema that is ignored by the evaluation process",
+  "properties": {
+    "name": {
+      "$comment": "TODO: Add `pattern` to better validate names",
+      "type": "string"
+    }
+  }
+}
+{{</schema>}}
+
+{{<instance-pass `Any string value is valid`>}}
+{ "name": "John Doe" }
+{{</instance-pass>}}

content/draft7/core/id.markdown

@@ -18,3 +18,170 @@ related:
   - vocabulary: core
     keyword: $schema
 ---
+
+The [`$id`]({{< ref "draft7/core/id" >}}) keyword explicitly turns a schema
+into a _schema resource_ (a schema that is associated with a URI). Relative
+URIs are resolved against the _current_ base URI, which is either the closest
+parent [`$id`]({{< ref "draft7/core/id" >}}) keyword (applicable in the case
+of compound schemas), or the base URI as determined by the context on which the
+schema is declared (i.e. serving a schema over HTTP _may_ implicitly award it
+such URL as the base).
+
+{{<learning-more>}}
+
+This keyword directly applies (without modifications or extensions) the concept
+of URIs to schemas. **If you are having a hard time following the concepts
+discussed in this page, it is probably because you don't have a strong grasp of
+URIs yet** (a notably hard but universal pre-requisite!).
+
+To learn more about URIs, we strongly suggest studying the [IETF RFC
+3986](https://www.rfc-editor.org/info/rfc3986) URI standard. To avoid
+confusion, note that there is also a [WHATWG URL
+Standard](https://url.spec.whatwg.org) that targets URLs in the context of web
+browsers. However, JSON Schema only implements and expects the IETF original
+standard.
+
+{{</learning-more>}}
+
+{{<common-pitfall>}}
+
+In JSON Schema, schema identifiers are merely identifiers and no behaviour is
+imposed on them. In particular, JSON Schema does not guarantee that a schema
+with an HTTP URL identifier is actually resolvable at such URL. To avoid
+surprises, JSON Schema implementations must be careful with automatically
+sending remote network requests when encountering supposely resolvable schema
+identifiers.
+
+{{</common-pitfall>}}
+
+{{<best-practice>}}
+
+It is strongly recommended for every schema file to explicitly declare an
+_absolute_ URI using this keyword. By doing so, you completely avoid various
+complex URI resolution edge cases, mainly when the base URI is implicit and
+context-dependent.
+
+If you are serving schemas over the network (i.e. over HTTP), it is common to
+set this keyword to the target URL. However, if your schemas are not accessible
+over the network, prefer using a
+[URN](https://en.wikipedia.org/wiki/Uniform_Resource_Name) (with a valid
+namespace registered by
+[IANA](https://www.iana.org/assignments/urn-namespaces/urn-namespaces.xhtml))
+or a non-locatable URI scheme such as a [Tag URI](https://www.taguri.org).
+
+{{</best-practice>}}
+
+To debug the role of the [`$id`]({{< ref "draft7/core/id" >}}) keyword on
+a schema (particularly schemas with embedded resources), try the [`jsonschema
+inspect`](https://github.com/sourcemeta/jsonschema/blob/main/docs/inspect.markdown)
+command. This command prints detailed information about each schema resource,
+subschema, location, and reference present in the schema. For example:
+
+```sh
+$ jsonschema inspect schema.json
+(RESOURCE) URI: https://example.com/schema
+    Type              : Static
+    Root              : https://example.com/schema
+    Pointer           :
+    Base              : https://example.com/schema
+    Relative Pointer  :
+    Dialect           : http://json-schema.org/draft-07/schema#
+    Base Dialect      : http://json-schema.org/draft-07/schema#
+    Parent            : <NONE>
+    Instance Location :
+
+...
+
+(SUBSCHEMA) URI: https://example.com/schema#/properties/foo
+    Type              : Static
+    Root              : https://example.com/schema
+    Pointer           : /properties/foo
+    Base              : https://example.com/schema
+    Relative Pointer  : /properties/foo
+    Dialect           : http://json-schema.org/draft-07/schema#
+    Base Dialect      : http://json-schema.org/draft-07/schema#
+    Parent            :
+    Instance Location : /foo
+
+...
+
+(REFERENCE) ORIGIN: /$schema
+    Type              : Static
+    Destination       : http://json-schema.org/draft-07/schema
+    - (w/o fragment)  : http://json-schema.org/draft-07/schema
+    - (fragment)      : <NONE>
+```
+
+## Examples
+
+{{<schema `A schema that declares a potentially resolvable HTTP absolute URL identifier`>}}
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://example.com/schemas/even-number.json",
+  "type": "number",
+  "multipleOf": 2
+}
+{{</schema>}}
+
+{{<schema `A schema that declares a non-resolvable Tag URI identifier`>}}
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "tag:example.com,2025:even-number",
+  "type": "number",
+  "multipleOf": 2
+}
+{{</schema>}}
+
+{{<schema `A schema that declares a non-resolvable URN example identifier`>}}
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "urn:example:even-number",
+  "type": "number",
+  "multipleOf": 2
+}
+{{</schema>}}
+
+{{<schema `A schema that uses fragment identifiers to create reusable anchors`>}}
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://example.com/schemas/user.json",
+  "type": "object",
+  "properties": {
+    "name": { "$ref": "#nonEmptyString" },
+    "email": { "$ref": "#nonEmptyString" }
+  },
+  "definitions": {
+    "nonEmptyString": {
+      "$id": "#nonEmptyString",
+      "type": "string",
+      "minLength": 1
+    }
+  }
+}
+{{</schema>}}
+
+{{<schema `A compound schema that declares relative and absolute nested URIs`>}}
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$comment": "This is the root schema resource",
+  "$id": "https://example.com/schemas/root.json",
+  "properties": {
+    "foo": {
+      "$comment": "The resolved URI of this nested schema resource is https://example.com/schemas/foo.json",
+      "$id": "foo.json"
+    },
+    "bar": {
+      "$comment": "The resolved URI of this nested schema resource is https://example.com/schemas/bar.json",
+      "$id": "/schemas/bar.json"
+    },
+    "baz": {
+      "$comment": "The resolved URI of this nested schema resource is https://absolute.example/baz.json",
+      "$id": "https://absolute.example/baz.json",
+      "items": {
+        "$comment": "The resolved URI of this nested schema resource is https://absolute.example/deep",
+        "$id": "deep"
+      }
+    }
+  }
+}
+{{</schema>}}