json-schema-org · jdesrosiers · Oct 21, 2024 · Oct 16, 2024 · Oct 16, 2024 · Oct 16, 2024
diff --git a/.eslintrc.json b/.eslintrc.json
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -1,9 +1,23 @@
 name: JSON Schema
 on:
   - push
+  - pull_request
+
 jobs:
-  specs:
-    runs-on: ubuntu-22.04
+  specs-markdown:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: latest
+          cache: npm
+      - run: npm ci
+      - run: npm run lint
+      - run: npm run build-all
+
+  specs-ietf:
+    runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
       - uses: actions/setup-python@v4

diff --git a/.gitignore b/.gitignore
@@ -1,10 +1,13 @@
-jsonschema-*.html
-jsonschema-*.pdf
-jsonschema-*.txt
+# Markdown builds
+web/
+
+# IETF builds
+json-schema-use-cases.html
+json-schema-use-cases.pdf
+json-schema-use-cases.txt
 relative-json-pointer.html
 relative-json-pointer.pdf
 relative-json-pointer.txt
-proposals/*.html
 
 # For the Python enviornment
 .venv

diff --git a/README.md b/README.md
@@ -29,7 +29,8 @@ To build the spec files to HTML from the Markdown sources, run `npm run
 build-all`.
 You can also build each individually with `npm run build -- filename.md`
 (Example: `npm run build -- jsonschema-core.md`). You can also use wildcards to
-build multiple specs at the same time: `npm run build -- jsonschema-*.md`.
+build multiple specs at the same time: `npm run build -- jsonschema-*.md`. The
+HTML files will be available in the `web` folder.
 
 The spec is built using [Remark](https://remark.js.org/), a markdown engine with
 good support for plugins and lots of existing plugins we can use.

diff --git a/build/build.js b/build/build.js
@@ -1,7 +1,8 @@
+/* eslint-disable no-console */
 import dotenv from "dotenv";
-import { readFileSync, writeFileSync } from "node:fs";
-import { dirname, basename } from "node:path";
-import { argv } from "node:process";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, resolve, relative } from "node:path";
+import { argv, cwd } from "node:process";
 import { reporter } from "vfile-reporter";
 import { remark } from "remark";
 import remarkCodeTitles from "./remark-code-titles.js";
@@ -10,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";
@@ -20,10 +22,11 @@ import rehypeStringify from "rehype-stringify";
 
 dotenv.config();
 
-const build = async (filename) => {
-  const md = readFileSync(filename, "utf-8");
-  const html = await remark()
+const build = async (filePath) => {
+  const md = await readFile(filePath, "utf-8");
+  const file = await remark()
     .use(remarkPresetLintMarkdownStyleGuide)
+    .use(remarkLintMaximumHeadingLength, false)
     .use(remarkGfm)
     .use(remarkHeadingId)
     .use(remarkHeadings, {
@@ -59,8 +62,12 @@ const build = async (filename) => {
     .use(rehypeStringify)
     .process(md);
 
-  const outfile = `${dirname(filename)}/${basename(filename, ".md")}.html`;
-  writeFileSync(outfile, `<!DOCTYPE html>
+  const rootPath = resolve(import.meta.dirname, "..");
+  const outPath = resolve(rootPath, "web");
+  const sourceRelativePath = relative(rootPath, filePath);
+  const outfile = resolve(outPath, sourceRelativePath).replace(/\.md$/, ".html");
+  await mkdir(dirname(outfile), { recursive: true });
+  await writeFile(outfile, `<!DOCTYPE html>
 <html>
   <head>
     <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/water.css@2/out/dark.css">
@@ -163,11 +170,13 @@ const build = async (filename) => {
     </style>
   </head>
   <body>
-    ${html.toString()}
+    ${file.toString()}
   </body>
 </html>`);
 
-  console.error(reporter(html));
+  console.error(reporter(file));
+
+  return file.messages.length;
 };
 
 (async function () {
@@ -176,9 +185,15 @@ const build = async (filename) => {
     console.error("WARNING: No files built. Usage: 'npm run build -- filename.md'");
   }
 
+  let messageCount = 0;
   for (const filename of files) {
     console.log(`Building: ${filename} ...`);
-    await build(filename);
+    const filePath = resolve(cwd(), filename);
+    messageCount += await build(filePath);
     console.log("");
   }
+
+  if (messageCount > 0) {
+    process.exit(1);
+  }
 }());
diff --git a/eslint.config.js b/eslint.config.js
@@ -0,0 +1,45 @@
+import js from "@eslint/js";
+import globals from "globals";
+import stylistic from "@stylistic/eslint-plugin";
+import importPlugin from "eslint-plugin-import";
+
+export default [
+  js.configs.recommended,
+  importPlugin.flatConfigs.recommended,
+  stylistic.configs.customize({
+    arrowParens: true,
+    braceStyle: "1tbs",
+    commaDangle: "never",
+    flat: true,
+    jsx: false,
+    quotes: "double",
+    semi: true
+  }),
+  {
+    languageOptions: {
+      ecmaVersion: "latest",
+      globals: {
+        ...globals.node
+      }
+    },
+    settings: {
+      "import/resolver": {
+        node: {}
+      }
+    },
+    rules: {
+      "no-unused-vars": ["error", { caughtErrorsIgnorePattern: "^_" }],
+      "no-empty-function": "off",
+      "no-console": ["error"],
+
+      // Imports
+      "import/extensions": ["error", "ignorePackages"],
+      "import/newline-after-import": ["error", { count: 2, exactCount: false, considerComments: true }], // Doesn't respect @import
+
+      // Stylistic
+      "@stylistic/yield-star-spacing": ["error", "after"],
+      "@stylistic/multiline-ternary": "off",
+      "@stylistic/no-multiple-empty-lines": ["error", { max: 2, maxEOF: 0, maxBOF: 0 }] // Allow max=2 for imports
+    }
+  }
+];
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.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/output/jsonschema-validation-output-machines.md b/output/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: