Fix spec markdown lint errors

jdesrosiers · jdesrosiers · commit 9d32eb6cd0ff · 2024-10-16T15:12:27.000-07:00
diff --git a/build/build.js b/build/build.js
@@ -11,6 +11,7 @@ import remarkGfm from "remark-gfm";
 import remarkHeadingId from "remark-heading-id";
 import remarkHeadings from "./remark-headings.js";
 import remarkPresetLintMarkdownStyleGuide from "remark-preset-lint-markdown-style-guide";
+import remarkLintMaximumHeadingLength from "remark-lint-maximum-heading-length";
 import remarkRehype from "remark-rehype";
 import remarkReferenceLinks from "./remark-reference-links.js";
 import remarkTableOfContents from "./remark-table-of-contents.js";
@@ -25,6 +26,7 @@ const build = async (filename) => {
   const md = readFileSync(filename, "utf-8");
   const file = await remark()
     .use(remarkPresetLintMarkdownStyleGuide)
+    .use(remarkLintMaximumHeadingLength, false)
     .use(remarkGfm)
     .use(remarkHeadingId)
     .use(remarkHeadings, {
diff --git a/jsonschema-core.md b/jsonschema-core.md
@@ -2051,7 +2051,7 @@ specified for the `application/json` media type. See [JSON](#rfc8259).
 Security considerations:: See {{security}} above.
 
 Interoperability considerations:: See Sections [6.2](#language),
-[6.3](#integers), and [6.4](#regex) above.
+[6.3](#data-model), and [6.4](#regex) above.
 
 Fragment identifier considerations:: See {{fragments}}
 
@@ -2072,7 +2072,7 @@ specified for the `application/json` media type. See [JSON](#rfc8259).
 Security considerations:: See {{security}} above.
 
 Interoperability considerations:: See Sections [6.2](#language),
-[6.3](#integers), and [6.4](#regex) above.
+[6.3](#data-model), and [6.4](#regex) above.
 
 Fragment identifier considerations:: See {{fragments}}
 
@@ -2467,32 +2467,48 @@ to the document.
 
 ### draft-bhutton-json-schema-next
 - Use IRIs instead of URIs, including allowing unicode in plain-name fragments
-- Clarify that detecting duplicate IRIs for different schemas SHOULD raise an error
+- Clarify that detecting duplicate IRIs for different schemas SHOULD raise an
+  error
 - Consolidate and clarify the syntax and rationale for plain-name fragments
 - "$id" MUST be an absolute-IRI, without any fragment, even an empty one
-- Note that an empty string "$id" results in duplicate IRIs for different schemas
+- Note that an empty string "$id" results in duplicate IRIs for different
+  schemas
 - Define empty schemas as empty (no longer allowing unrecognized keywords)
-- Clarify that if unknown properties are not treated as annotations, they MUST be ignored
-- Remove outdated pre-annotation-collection section on annotation-applicator interaction
+- Clarify that if unknown properties are not treated as annotations, they MUST
+  be ignored
+- Remove outdated pre-annotation-collection section on annotation-applicator
+  interaction
 - Clarify that regular expressions are not anchored
-- Specify valid implementation-defined options for handling schemas without "$schema"
-- Clarify that vocabularies omitted from "$vocabulary" MUST NOT be available for use
-- Clarify that standard keywords are only available as vocabulary keywords, subject to "$vocabulary" control
-- Clarify the nature and purpose of optional (set to false in "$vocabulary") vocabularies
-- Clarify that optional simple-annotation-only vocabularies can be supported without custom code
-- Fix typo that "$vocabulary" can only be in a document root; it is legal in resource roots
+- Specify valid implementation-defined options for handling schemas without
+  "$schema"
+- Clarify that vocabularies omitted from "$vocabulary" MUST NOT be available for
+  use
+- Clarify that standard keywords are only available as vocabulary keywords,
+  subject to "$vocabulary" control
+- Clarify the nature and purpose of optional (set to false in "$vocabulary")
+  vocabularies
+- Clarify that optional simple-annotation-only vocabularies can be supported
+  without custom code
+- Fix typo that "$vocabulary" can only be in a document root; it is legal in
+  resource roots
 - Remove bookending requirement for `$dynamicRef`
 - Clarify that "prefixItems" does not constrain the length of an array
-- Move "minContains" and "maxContains" to the applicator vocabulary from validation
+- Move "minContains" and "maxContains" to the applicator vocabulary from
+  validation
 - "minContains" and "maxContains" no longer have their own assertion results
 - "contains" assertion result now depends on "minContains" and "maxContains"
-- Affirm that no keyword can un-fail an adjacent keyword ("minContains" previously violated this)
-- "contains", "minContains", and "maxContains" now apply to objects as well as arrays
+- Affirm that no keyword can un-fail an adjacent keyword ("minContains"
+  previously violated this)
+- "contains", "minContains", and "maxContains" now apply to objects as well as
+  arrays
 - As an object keyword, "contains" now affects "unevaluatedProperties"
 - Add `propertyDependencies` keyword
-- Add new "list" and "hierarchical" output formats in place of "basic", "detailed", and "verbose"
-- Rename "absoluteKeywordLocation" and "keywordLocation" to "schemaLocation" and "evaluationPath"
-- Output units in new format group by "schemaLocation", "instanceLocation", and "evaluationPath"
+- Add new "list" and "hierarchical" output formats in place of "basic",
+  "detailed", and "verbose"
+- Rename "absoluteKeywordLocation" and "keywordLocation" to "schemaLocation" and
+  "evaluationPath"
+- Output units in new format group by "schemaLocation", "instanceLocation", and
+  "evaluationPath"
 - Add "droppedAnnotations" to output formats
 
 ### draft-bhutton-json-schema-01
diff --git a/jsonschema-validation-output-machines.md b/jsonschema-validation-output-machines.md
@@ -172,10 +172,14 @@ The failing instance will produce the following errors:
   is not a number.
 
 <!--
-"minimum" doesn't produce an error because it only operates on instances that are numbers.
+"minimum" doesn't produce an error because it only operates on instances that
+are numbers.
 -->
 <!--
-Note that the error message wording as depicted in the examples below is not a requirement of this specification.  Implementations SHOULD craft error messages tailored for their audience or provide a templating mechanism that allows their users to craft their own messages.
+Note that the error message wording as depicted in the examples below is not a
+requirement of this specification. Implementations SHOULD craft error messages
+tailored for their audience or provide a templating mechanism that allows their
+users to craft their own messages.
 -->
 
 The passing instance will produce the following annotations:
diff --git a/jsonschema-validation.md b/jsonschema-validation.md
@@ -234,9 +234,9 @@ Omitting this keyword has the same behavior as a value of 0.
 
 The value of this keyword MUST be a boolean.
 
-If this keyword has boolean value `false`, the instance validates successfully. If
-it has boolean value `true`, the instance validates successfully if all of its
-elements are unique.
+If this keyword has boolean value `false`, the instance validates successfully.
+If it has boolean value `true`, the instance validates successfully if all of
+its elements are unique.
 
 Omitting this keyword has the same behavior as a value of `false`.
 
@@ -317,8 +317,8 @@ which choose to support assertion behavior:
 
 - MUST still collect the keyword's value as an annotation (if the implementation
   supports annotation collection),
-- MUST provide a configuration option to enable assertion behavior, defaulting to
-  annotation-only behavior
+- MUST provide a configuration option to enable assertion behavior, defaulting
+  to annotation-only behavior
 - SHOULD provide an implementation-specific best effort validation for each
   format attribute defined below;[^3]
 - MAY choose to implement validation of any or all format attributes as a no-op
@@ -662,7 +662,8 @@ associated schema.
 
 The value of this keyword MUST be a boolean. When multiple occurrences of this
 keyword are applicable to a single sub-instance, applications SHOULD consider
-the instance location to be deprecated if any occurrence specifies a `true` value.
+the instance location to be deprecated if any occurrence specifies a `true`
+value.
 
 If `deprecated` has a value of boolean `true`, it indicates that applications
 SHOULD refrain from usage of the declared property. It MAY mean the property is
@@ -695,11 +696,11 @@ An instance document that is marked as `readOnly` for the entire document MAY be
 ignored if sent to the owning authority, or MAY result in an error, at the
 authority's discretion.
 
-If `writeOnly` has a value of boolean `true`, it indicates that the value is never
-present when the instance is retrieved from the owning authority. It can be
-present when sent to the owning authority to update or create the document (or
-the resource it represents), but it will not be included in any updated or newly
-created version of the instance.
+If `writeOnly` has a value of boolean `true`, it indicates that the value is
+never present when the instance is retrieved from the owning authority. It can
+be present when sent to the owning authority to update or create the document
+(or the resource it represents), but it will not be included in any updated or
+newly created version of the instance.
 
 An instance document that is marked as `writeOnly` for the entire document MAY
 be returned as a blank document of some sort, or MAY produce an error upon
@@ -899,9 +900,12 @@ to the document.
 
 - *draft-next*
     - Use IRIs instead of URIs
-    - Move "minContains" and "maxContains" to the applicator vocabulary (see also that changelog)
-    - Remove the optional automatic second-pass validation of "content*" keywords
-    - Clarify that "contentSchema"'s value is a schema just like any other subschema
+    - Move "minContains" and "maxContains" to the applicator vocabulary (see
+      also that changelog)
+    - Remove the optional automatic second-pass validation of "content*"
+      keywords
+    - Clarify that "contentSchema"'s value is a schema just like any other
+      subschema
 - *draft-bhutton-json-schema-validation-01*
     - Improve and clarify the `minContains` keyword explanation
     - Remove the use of "production" in favour of "ABNF rule"
diff --git a/proposals/propertyDependencies-adr.md b/proposals/propertyDependencies-adr.md
@@ -1,14 +1,16 @@
 # Add New Keyword: `propertyDependencies`
 
-* Status: proposed
-* Deciders: @gregsdennis, @jdesrosiers, @relequestual
-* Date: 2022-04-07
+- Status: proposed
+- Deciders: @gregsdennis, @jdesrosiers, @relequestual
+- Date: 2022-04-07
 
 Technical Story:
 
-- Issue discussing feature - https://github.com/json-schema-org/json-schema-spec/issues/1082
-- PR to add to the spec - https://github.com/json-schema-org/json-schema-spec/pull/1143
-- ADR to extract from the spec and use feature life cycle - https://github.com/json-schema-org/json-schema-spec/pull/1505
+- Issue discussing feature - <https://github.com/json-schema-org/json-schema-spec/issues/1082>
+- PR to add to the spec - <https://github.com/json-schema-org/json-schema-spec/pull/1143>
+- ADR to extract from the spec and use feature life cycle - <https://github.com/json-schema-org/json-schema-spec/pull/1505>
+
+## Table of Contents
 
 ## Context and Problem Statement
 
@@ -33,7 +35,8 @@ adopt or redefine `discriminator`.
 
 ## Considered Options
 
-All of the following options have the same validation result as the following schema.
+All of the following options have the same validation result as the following
+schema.
 
 ```json
 {
@@ -64,10 +67,10 @@ that concept to solve this problem.
 }
 ```
 
-* Good, because it handle the most common use case: string property values
-* Good, because all property values are grouped together
-* Good, because it's less verbose
-* Bad, because it doesn't handle non-string property values
+- Good, because it handle the most common use case: string property values
+- Good, because all property values are grouped together
+- Good, because it's less verbose
+- Bad, because it doesn't handle non-string property values
 
 ### Option 2
 
@@ -97,7 +100,9 @@ prone.
 * Good, because it supports all use cases
 * Bad, because properties are not naturally grouped together
 * Bad, because it's quite verbose
-* Bad, because we have no precedent for a keyword which explicitly defines its own properties.  This would be new operational functionality, which we try to avoid if we can.
+* Bad, because we have no precedent for a keyword which explicitly defines its
+  own properties. This would be new operational functionality, which we try to
+  avoid if we can.
 
 ### Option 3
 
@@ -124,7 +129,9 @@ object. It's still too verbose.
 * Good, because it supports all use cases
 * Good, because all property values are grouped together
 * Bad, because it's quite verbose
-* Bad, because we have no precedent for a keyword which explicitly defines its own properties.  This would be new operational functionality, which we try to avoid if we can.
+* Bad, because we have no precedent for a keyword which explicitly defines its
+  own properties. This would be new operational functionality, which we try to
+  avoid if we can.
 
 ### Option 4
 
@@ -148,10 +155,11 @@ naming aside), but otherwise has all the same problems as the other examples.
 }
 ```
 
-* Good, because it supports all use cases
-* Bad, because properties are not naturally grouped together
-* Bad, because it's very verbose
-* Bad, because it introduces a lot of inter-keyword dependencies, which we'd have to exhaustively define
+- Good, because it supports all use cases
+- Bad, because properties are not naturally grouped together
+- Bad, because it's very verbose
+- Bad, because it introduces a lot of inter-keyword dependencies, which we'd
+  have to exhaustively define
 
 ### Option 5
 
@@ -183,7 +191,8 @@ verbose.
 * Good, because it's a familiar syntax
 * Bad, because properties are not naturally grouped together
 * Bad, because it's very verbose
-* Bad, because `ifProperties` is very niche.  Will this spawn a new series of `if*` keywords?  How would it interact with `if`?
+* Bad, because `ifProperties` is very niche.  Will this spawn a new series of
+  `if*` keywords?  How would it interact with `if`?
 
 ### Option 6
 
diff --git a/proposals/propertyDependencies.md b/proposals/propertyDependencies.md
@@ -39,7 +39,8 @@ specification](../jsonschema-core.html) also apply to this document.
 A common need in JSON Schema is to select between one schema or another to
 validate an instance based on the value of some property in the JSON instance.
 There are a several patterns people use to accomplish this, but they all have
-significant [problems](propertyDependencies-adr.md#problems). <!-- Update when moving ADR -->
+significant [problems](propertyDependencies-adr.md#problems). <!-- Update when
+moving ADR -->
 
 OpenAPI solves this problem with the `discriminator` keyword. However, their
 approach is more oriented toward code generation concerns, is poorly specified
@@ -88,26 +89,31 @@ those goals means that some trade-offs need to be made.
 
 ## Change Description
 
-The `propertyDependencies` keyword will be added to the `https://json-schema.org/vocab/applicator` [applicator
+The `propertyDependencies` keyword will be added to the
+`https://json-schema.org/vocab/applicator` [applicator
 vocabulary](../jsonschema-core.html#applicatorvocab).
 
-1. The following will be added to the JSON Schema Core specification as a
+1.  The following will be added to the JSON Schema Core specification as a
 subsection of "Keywords for Applying Subschemas Conditionally".
     > ### `propertyDependencies`
     >
     > This keyword specifies subschemas that are evaluated if the instance is an
     > object and contains a certain property with a certain string value.
     >
-    > This keyword's value MUST be an object. Each value in the object MUST be an
-    > object whose values MUST be valid JSON Schemas.
+    > This keyword's value MUST be an object. Each value in the object MUST be
+    > an object whose values MUST be valid JSON Schemas.
     >
-    > If the outer object key is a property in the instance and the inner object key
-    > is equal to the value of that property, the entire instance must validate
-    > against the schema. Its use is dependent on the presence and value of the
-    > property.
+    > If the outer object key is a property in the instance and the inner object
+    > key is equal to the value of that property, the entire instance must
+    > validate against the schema. Its use is dependent on the presence and
+    > value of the property.
     >
     > Omitting this keyword has the same behavior as an empty object.
-2. The following subschema will be added to the Applicator Vocabulary schema, `https://json-schema.org/<version>/<release>/meta/applicator` at `/properties/propertyDependencies`:
+
+2.  The following subschema will be added to the Applicator Vocabulary schema,
+   `https://json-schema.org/<version>/<release>/meta/applicator` at
+   `/properties/propertyDependencies`:
+
     ```json
     {
       "type": "object",
@@ -124,9 +130,9 @@ subsection of "Keywords for Applying Subschemas Conditionally".
 
 ## [Appendix] Change Log
 
-* [March 2021] - Initially proposed
-* [October 2021] Added to specification document
-* [May 2024] Extracted from specification document as experimental feature
+- [March 2021] - Initially proposed
+- [October 2021] Added to specification document
+- [May 2024] Extracted from specification document as experimental feature
 
 ## Champions
 
diff --git a/proposals/proposal-template.md b/proposals/proposal-template.md
@@ -3,8 +3,8 @@
 ## Abstract
 
 <!--
-Fill in the specification(s) that will change.  If adding a keyword, which vocabulary
-will contain it?
+Fill in the specification(s) that will change.  If adding a keyword, which
+vocabulary will contain it?
 
 For example
 
diff --git a/proposals/vocabularies-adr.md b/proposals/vocabularies-adr.md
diff --git a/proposals/vocabularies.md b/proposals/vocabularies.md
