Recommend the inspect CLI command in more places

Signed-off-by: Juan Cruz Viotti <[email protected]>

Author: jviotti

content/2020-12/core/anchor.markdown

@@ -65,6 +65,40 @@ itself.
 
 {{</common-pitfall>}}
 
+To debug anchors and how JSON Schema is interpreting your relative URIs, try
+the [`jsonschema
+inspect`](https://github.com/sourcemeta/jsonschema/blob/main/docs/inspect.markdown)
+command. This command prints detailed information about each schema reference
+and of each anchor in the schema. For example:
+
+```sh
+$ jsonschema inspect schema.json
+
+...
+
+(ANCHOR) URI: https://example.com/person#internal-string
+    Type              : Static
+    Root              : https://example.com/person
+    Pointer           : /$defs/nonEmptyString
+    Base              : https://example.com/person
+    Relative Pointer  : /$defs/nonEmptyString
+    Dialect           : https://json-schema.org/draft/2020-12/schema
+    Base Dialect      : https://json-schema.org/draft/2020-12/schema
+    Parent            :
+    Instance Location : /firstName
+    Instance Location : /lastName
+
+...
+
+(REFERENCE) ORIGIN: /properties/firstName/$ref
+    Type              : Static
+    Destination       : https://example.com/person#internal-string
+    - (w/o fragment)  : https://example.com/person
+    - (fragment)      : internal-string
+
+...
+```
+
 ## Examples
 
 {{<schema `A schema that declares a helper schema associated with a location-independent identifier`>}}

content/2020-12/core/id.markdown

@@ -84,6 +84,47 @@ or a non-locatable URI scheme such as a [Tag URI](https://www.taguri.org).
 
 {{</best-practice>}}
 
+To debug the role of the `$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           : https://json-schema.org/draft/2020-12/schema
+    Base Dialect      : https://json-schema.org/draft/2020-12/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           : https://json-schema.org/draft/2020-12/schema
+    Base Dialect      : https://json-schema.org/draft/2020-12/schema
+    Parent            :
+    Instance Location : /foo
+
+...
+
+(REFERENCE) ORIGIN: /$schema
+    Type              : Static
+    Destination       : https://json-schema.org/draft/2020-12/schema
+    - (w/o fragment)  : https://json-schema.org/draft/2020-12/schema
+    - (fragment)      : <NONE>
+```
+
 ## Examples
 
 {{<schema `A schema that declares a potentially resolvable HTTP absolute URL identifier`>}}

content/2020-12/core/ref.markdown

@@ -39,7 +39,7 @@ be created out of simpler ones. A reference may set its URI fragment to a [JSON
 Pointer](https://www.rfc-editor.org/rfc/rfc6901) that determines the
 destination of the reference after first resolving the rest of the URI.
 
-{{<common-pitfall>}} 
+{{<common-pitfall>}}
 
 **Avoid referencing other schema files using their file paths**. While some
 implementations support this by automatically constructing schema URIs that
@@ -48,9 +48,9 @@ standard and guaranteed mechanism of declaring a schema URI for identification
 and referencing purposes is through the [`$id`]({{< ref "2020-12/core/id" >}})
 keyword.
 
-{{</common-pitfall>}} 
+{{</common-pitfall>}}
 
-{{<common-pitfall>}} 
+{{<common-pitfall>}}
 
 The target of a reference must be a schema. Referencing a JSON value that is
 not unambiguously recognised as a schema leads to undefined behaviour.  This
@@ -59,7 +59,7 @@ referencing parts of a schema that a JSON Schema evaluator does not consider to
 be a subschema.  For example, referencing the contents of the [`examples`]({{<
 ref "2020-12/meta-data/examples" >}}) keyword.
 
-{{</common-pitfall>}} 
+{{</common-pitfall>}}
 
 References are either _internal_ (pointing at schemas within the same schema
 definition) or _external_ (pointing at schema resources outside the given
@@ -71,19 +71,19 @@ are notable examples of the latter. A relative reference from a schema embedded
 in an OpenAPI specification is resolved from the root of the API specification,
 and not from the root of the schema.
 
-{{<best-practice>}} 
+{{<best-practice>}}
 
 It is highly recommended to make use of _external_ references to break down
 complex monolithic schemas into smaller schema files. However, for performance
 and integrity reasons, avoid resolving these external schemas (i.e.  over HTTP
-or the filesystem) at runtime. 
+or the filesystem) at runtime.
 
 You can automatically inline external references at build time using the
 [`jsonschema
 bundle`](https://github.com/sourcemeta/jsonschema/blob/main/docs/bundle.markdown)
 command.
 
-{{</best-practice>}} 
+{{</best-practice>}}
 
 Note that a reference to an absolute URI does not necessarily mean that the
 reference is external. Conversely, a reference to a relative URI does not
@@ -97,7 +97,7 @@ is considered internal. This internal-first lookup is what enables the standard
 ](https://json-schema.org/blog/posts/bundling-json-schema-compound-documents)
 process.
 
-{{<learning-more>}} 
+{{<learning-more>}}
 
 If you are having a hard time understanding references and some of its more
 subtle scenarios (like base URI resolution), it is probably because you don't
@@ -116,8 +116,8 @@ representation](https://www.rfc-editor.org/rfc/rfc6901#section-6).
 
 {{</learning-more>}}
 
-To debug references and how JSON Schema is interpreting your specific relative
-URIs, try the [`jsonschema
+To debug references and how JSON Schema is interpreting your relative URIs, try
+the [`jsonschema
 inspect`](https://github.com/sourcemeta/jsonschema/blob/main/docs/inspect.markdown)
 command. This command prints detailed information about each schema reference
 and of each location of the schema. For example:
@@ -142,22 +142,22 @@ $ jsonschema inspect schema.json
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://example.com/my-schema",
   "properties": {
-    "byRelativeFragmentPointer": { 
+    "byRelativeFragmentPointer": {
       "$ref": "#/$defs/helper"
     },
-    "byAbsoluteFragmentPointer": { 
+    "byAbsoluteFragmentPointer": {
       "$ref": "https://example.com/my-schema#/$defs/helper"
     },
-    "byRelativeURI": { 
+    "byRelativeURI": {
       "$ref": "my-helper"
     },
-    "byRelativeRootPathURI": { 
+    "byRelativeRootPathURI": {
       "$ref": "/my-helper"
     },
-    "byRelativeBackslashURI": { 
+    "byRelativeBackslashURI": {
       "$ref": "my-schema/../my-helper"
     },
-    "byAbsoluteURI": { 
+    "byAbsoluteURI": {
       "$ref": "https://example.com/my-helper"
     }
   },
@@ -175,16 +175,16 @@ $ jsonschema inspect schema.json
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://example.com/my-schema",
   "properties": {
-    "byAbsoluteURI": { 
+    "byAbsoluteURI": {
       "$ref": "https://example.com/my-other-schema"
     },
-    "byRelativeURI": { 
+    "byRelativeURI": {
       "$ref": "my-other-schema"
     },
-    "byRelativeRootPathURI": { 
+    "byRelativeRootPathURI": {
       "$ref": "/my-other-schema"
     },
-    "byRelativeBackslashURI": { 
+    "byRelativeBackslashURI": {
       "$ref": "my-schema/../my-other-schema"
     }
   }
@@ -195,7 +195,7 @@ $ jsonschema inspect schema.json
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "properties": {
-    "byAbsoluteURI": { 
+    "byAbsoluteURI": {
       "$ref": "urn:example:my-other-schema"
     }
   }