doc-model.js 1.5.2 → 1.6.0

package/README.md

@@ -10,7 +10,7 @@ Both `ooxml.js` and `documents.js` independently arrived at the same content voc
 
 It contains only [Zod](https://zod.dev) schemas, their inferred types, and a handful of trivial schema-attached helpers (hex-colour conversion, a recursive structural type guard for the mutually-recursive table/block/embedded-object types). There is no XML, ZIP, PDF, or other binary handling here, and no `zod` dependency other than `zod` itself.
 
-The GitHub repository is [`ExaDev/document-schema.js`](https://github.com/ExaDev/document-schema.js), matching the published npm package name; `document-content-model` (the repository's original name, kept resolving), `doc-model.js`, `doc-schema.js`, `document-schema`, and `document-model.js` republish the identical build as aliases on npmjs.org, alongside a scoped `@exadev/document-content-model` alias on GitHub Packages. A CI matrix job (`publish-aliases` in `.github/workflows/ci.yml`) rewrites `package.json`'s `name` and registry via `npm pkg set` after each release and publishes under each alias in turn -- install whichever name you already depend on.
+The GitHub repository is [`ExaDev/document-schema.js`](https://github.com/ExaDev/document-schema.js), matching the published npm package name.
 
 ## Usage
 
@@ -22,6 +22,26 @@ const layout = LayoutDocumentSchema.parse(somePageLayoutValue);
 const pkg = DocumentPackageSchema.parse({ formatVersion: 1, content, layout });
 ```
 
+## JSON Schema
+
+Alongside the Zod schemas/types above, the package publishes three plain [JSON Schema](https://json-schema.org) files -- generated from the same Zod definitions via [`z.toJSONSchema()`](https://zod.dev/json-schema) at build time (`scripts/generate-json-schemas.mjs`) -- for non-TypeScript consumers that want to validate against or generate types from these shapes without depending on Zod at all:
+
+```ts
+const documentPackageSchema = require('document-schema.js/schemas/document-package.schema.json');
+// or, from a bundler/toolchain that supports JSON module imports:
+import documentPackageSchema from 'document-schema.js/schemas/document-package.schema.json' with { type: 'json' };
+```
+
+or from any language/tool that can read a file out of `node_modules`:
+
+```
+node_modules/document-schema.js/schemas/document-package.schema.json
+node_modules/document-schema.js/schemas/content-document.schema.json
+node_modules/document-schema.js/schemas/layout-document.schema.json
+```
+
+Each file's `$id` is a commit-SHA-pinned `https://raw.githubusercontent.com/ExaDev/document-schema.js/<sha>/schemas/<file>` URL -- immutable, and cross-referenced between the three files via real `$ref`s (e.g. `document-package.schema.json`'s `content`/`layout` properties `$ref` the other two files directly), so a JSON Schema validator that resolves `$ref`s over HTTP (or against local copies of all three files) can validate a whole `DocumentPackage` value. `content-document.schema.json` additionally carries a `$defs` block for the recursive paragraph/table/embedded-object block model, which Zod's own converter can't express directly (see that script's own top-of-file comment for why).
+
 ## Used by
 
 - [ooxml.js](https://github.com/ExaDev/ooxml.js) — its `readDocx`/`readPptx`/`readXlsxContent` return `ContentSection[]`/`ContentSlide[]`/spreadsheet `ContentSheet[]` typed against this package's own schemas, not a locally-defined lookalike.
@@ -29,7 +49,7 @@ const pkg = DocumentPackageSchema.parse({ formatVersion: 1, content, layout });
 - [documents.js](https://github.com/ExaDev/documents.js) — the primary consumer of both `ContentDocument` and `LayoutDocument`, which it converts between via its layout engines and its `pdf-codec` dependency, and of `DocumentPackage` as the `onDocument` side-channel value its conversion functions hand back.
 - [pdf-codec](https://github.com/ExaDev/pdf-codec) — the hand-written PDF codec extracted from `documents.js`: `readPdf`/`writePdf` and its own `pdfCodec` z.codec() pair operate entirely in terms of this package's `LayoutDocument` (plus the item kinds it's built from -- `LayoutItem`/`LayoutText`/`LayoutImage`/`LayoutRect`/`LayoutEllipse`/`LayoutLink`/`LayoutPath`/`LayoutSubpath`/`LayoutPathSegment`/`LayoutPage`/`LayoutImageAsset`/`LayoutMetadata`), `Color`/`LayoutFont` (aliased `LayoutColor`/`LayoutFont` at its own call sites), and `LAYOUT_FORMAT_VERSION`/`COLOR_BLACK`/`LayoutDocumentSchema` -- it never redeclares any of these itself, unlike its own `MathBox`/`PositionedFormula` mirror of `documents.js`'s MathML types (a deliberate, narrower exception -- see pdf-codec's own README).
 
-None of these four packages depend on each other for this vocabulary — each depends on `document-schema.js` (or one of its aliases above) directly, which is the whole point: one schema, not four independently-maintained, drift-prone copies.
+None of these four packages depend on each other for this vocabulary — each depends on `document-schema.js` directly, which is the whole point: one schema, not four independently-maintained, drift-prone copies.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "doc-model.js",
-  "version": "1.5.2",
+  "version": "1.6.0",
   "description": "The canonical, format-agnostic content and layout schemas shared by ooxml.js, odf.js, and documents.js -- pure Zod schemas, no behaviour.",
   "type": "module",
   "repository": {
@@ -19,13 +19,17 @@
       },
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
-    }
+    },
+    "./schemas/document-package.schema.json": "./schemas/document-package.schema.json",
+    "./schemas/content-document.schema.json": "./schemas/content-document.schema.json",
+    "./schemas/layout-document.schema.json": "./schemas/layout-document.schema.json"
   },
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "schemas"
   ],
   "publishConfig": {
     "access": "public",
@@ -73,13 +77,13 @@
     "vitest": "^4.1.10"
   },
   "scripts": {
-    "build": "tsdown",
+    "build": "tsdown && node scripts/generate-json-schemas.mjs",
     "lint": "eslint . --max-warnings 0",
     "typecheck": "tsc --noEmit",
     "test": "vitest run --project unit",
     "test:watch": "vitest --project unit",
     "test:coverage": "vitest run --project unit --coverage",
-    "test:smoke": "tsdown && vitest run --project smoke",
+    "test:smoke": "pnpm run build && vitest run --project smoke",
     "release": "semantic-release"
   }
 }