document-schema.js 1.6.0 → 1.7.0

package/README.md

@@ -40,7 +40,36 @@ 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).
+Each file's `$id` is a `https://cdn.jsdelivr.net/npm/document-schema.js@<version>/schemas/<file>` URL, pinned to the exact npm version that generated it -- immutable (jsdelivr serves each version's own published tarball contents forever, with an immutable cache header) and genuinely live the moment that version is published, unlike a commit-SHA-pinned raw GitHub URL would be: a gitignored, generated file can never actually be committed at the commit whose SHA it would need to embed, since committing it changes the tree and thus the hash. The three files are cross-referenced via real `$ref`s (e.g. `document-package.schema.json`'s `content`/`layout` properties `$ref` the other two files directly, at that same version), 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).
+
+### Self-describing JSON
+
+`documentPackageWithSchema`/`contentDocumentWithSchema`/`layoutDocumentWithSchema` each take a real `DocumentPackage`/`ContentDocument`/`LayoutDocument` value and return the same value with a `$schema` property added, pointing at the `.schema.json` file above for the *currently installed* package version:
+
+```ts
+import { documentPackageWithSchema } from 'document-schema.js';
+
+const tagged = documentPackageWithSchema(pkg);
+// { $schema: 'https://cdn.jsdelivr.net/npm/document-schema.js@1.6.1/schemas/document-package.schema.json', formatVersion: 1, content: {...}, layout: {...} }
+writeFileSync('package.json.doc', JSON.stringify(tagged, null, 2));
+```
+
+A caller who already knows the kind can keep ingesting with the existing schemas directly -- `DocumentPackageSchema.parse(value)` (etc.) already tolerates and silently strips an incoming `$schema` property, since none of these schemas are `.strict()`. `documentFromJson` exists for the "don't yet know the kind" case: it reads `$schema` to decide which of the three schemas to run, then that schema does the real structural validation:
+
+```ts
+import { documentFromJson, UnrecognizedDocumentSchemaError } from 'document-schema.js';
+
+try {
+  const { kind, value } = documentFromJson(JSON.parse(readFileSync('some-file.json', 'utf8')));
+  // kind: 'DocumentPackage' | 'ContentDocument' | 'LayoutDocument'
+} catch (error) {
+  if (error instanceof UnrecognizedDocumentSchemaError) {
+    console.error('not a document-schema.js value:', error.schema);
+  }
+}
+```
+
+`documentSchemaKindOf(value)` is the lower-level building block `documentFromJson` uses internally -- exported on its own for a caller that only wants to know which kind a value claims to be (version-agnostically: a `$schema` from an older or newer installed version still resolves), without also parsing it. `schemaUriFor(kind)` is the URL builder itself, also exported directly. Deliberately not added: a JSON-Schema-validator dependency (e.g. `ajv`) for ingest -- the generated `.schema.json` files are already a strictly *weaker* approximation of the real Zod schemas (see the two hand-authored `$defs` fragments above), so re-validating against them on ingest would be a fidelity regression, not an improvement.
 
 ## Used by
 

package/dist/index.cjs

@@ -141,29 +141,29 @@ const ContentPageBreakSchema = zod.z.object({
 	kind: zod.z.literal("pageBreak"),
 	sourcePath: zod.z.string().optional()
 });
-function isRecord(value) {
+function isRecord$1(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function isContentRun(value) {
-	return isRecord(value) && typeof value.text === "string";
+	return isRecord$1(value) && typeof value.text === "string";
 }
 function isContentTableCell(value) {
-	return isRecord(value) && Array.isArray(value.blocks) && value.blocks.every(isContentBlock);
+	return isRecord$1(value) && Array.isArray(value.blocks) && value.blocks.every(isContentBlock);
 }
 function isContentTableRow(value) {
-	return isRecord(value) && Array.isArray(value.cells) && value.cells.every(isContentTableCell) && (value.heightPt === void 0 || typeof value.heightPt === "number");
+	return isRecord$1(value) && Array.isArray(value.cells) && value.cells.every(isContentTableCell) && (value.heightPt === void 0 || typeof value.heightPt === "number");
 }
 function isContentEmbeddedObjectKind(value) {
 	return value === "formula" || value === "wordprocessing" || value === "presentation" || value === "spreadsheet" || value === "drawing";
 }
 function isContentEmbeddedObject(value) {
-	return isRecord(value) && isContentEmbeddedObjectKind(value.objectKind) && BoxSchema.safeParse(value.frame).success && ContentDocumentSchema.safeParse(value.document).success;
+	return isRecord$1(value) && isContentEmbeddedObjectKind(value.objectKind) && BoxSchema.safeParse(value.frame).success && ContentDocumentSchema.safeParse(value.document).success;
 }
 function isContentEmbeddedObjectBlock(value) {
-	return isRecord(value) && value.kind === "embeddedObject" && isContentEmbeddedObject(value);
+	return isRecord$1(value) && value.kind === "embeddedObject" && isContentEmbeddedObject(value);
 }
 function isContentBlock(value) {
-	if (!isRecord(value)) return false;
+	if (!isRecord$1(value)) return false;
 	const kind = value.kind;
 	if (kind === "paragraph") return Array.isArray(value.runs) && value.runs.every(isContentRun);
 	if (kind === "image") return (value.format === "png" || value.format === "jpeg") && typeof value.base64 === "string" && typeof value.widthPt === "number" && typeof value.heightPt === "number";
@@ -537,6 +537,81 @@ const DocumentPackageSchema = zod.z.object({
 	layout: LayoutDocumentSchema.optional()
 });
 //#endregion
+//#region src/schema-io.ts
+const SCHEMA_FILE_NAMES = {
+	DocumentPackage: "document-package.schema.json",
+	ContentDocument: "content-document.schema.json",
+	LayoutDocument: "layout-document.schema.json"
+};
+function schemaUriFor(kind) {
+	return `https://cdn.jsdelivr.net/npm/document-schema.js@1.7.0/schemas/${SCHEMA_FILE_NAMES[kind]}`;
+}
+const SCHEMA_URI_PATTERN = /^https:\/\/cdn\.jsdelivr\.net\/npm\/document-schema\.js@[^/]+\/schemas\/(document-package|content-document|layout-document)\.schema\.json$/;
+function kindForFileStem(stem) {
+	switch (stem) {
+		case "document-package": return "DocumentPackage";
+		case "content-document": return "ContentDocument";
+		case "layout-document": return "LayoutDocument";
+		default: return;
+	}
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function documentSchemaKindOf(value) {
+	if (!isRecord(value)) return void 0;
+	if (!("$schema" in value) || typeof value.$schema !== "string") return void 0;
+	const match = SCHEMA_URI_PATTERN.exec(value.$schema);
+	if (match === null) return void 0;
+	const stem = match[1];
+	if (stem === void 0) return void 0;
+	return kindForFileStem(stem);
+}
+function documentPackageWithSchema(value) {
+	return {
+		$schema: schemaUriFor("DocumentPackage"),
+		...value
+	};
+}
+function contentDocumentWithSchema(value) {
+	return {
+		$schema: schemaUriFor("ContentDocument"),
+		...value
+	};
+}
+function layoutDocumentWithSchema(value) {
+	return {
+		$schema: schemaUriFor("LayoutDocument"),
+		...value
+	};
+}
+var UnrecognizedDocumentSchemaError = class extends Error {
+	schema;
+	constructor(schema) {
+		super(`documentFromJson: value has no recognized "$schema" property (expected one of the three document-schema.js .schema.json URIs; found: ${JSON.stringify(schema)}).`);
+		this.name = "UnrecognizedDocumentSchemaError";
+		this.schema = schema;
+	}
+};
+function documentFromJson(value) {
+	const kind = documentSchemaKindOf(value);
+	if (kind === void 0) throw new UnrecognizedDocumentSchemaError(isRecord(value) ? value.$schema : void 0);
+	switch (kind) {
+		case "DocumentPackage": return {
+			kind,
+			value: DocumentPackageSchema.parse(value)
+		};
+		case "ContentDocument": return {
+			kind,
+			value: ContentDocumentSchema.parse(value)
+		};
+		case "LayoutDocument": return {
+			kind,
+			value: LayoutDocumentSchema.parse(value)
+		};
+	}
+}
+//#endregion
 exports.AlignmentSchema = AlignmentSchema;
 exports.BoxSchema = BoxSchema;
 exports.COLOR_BLACK = COLOR_BLACK;
@@ -595,8 +670,16 @@ exports.MarginsSchema = MarginsSchema;
 exports.PAGE_SIZE_A4 = PAGE_SIZE_A4;
 exports.PAGE_SIZE_LETTER = PAGE_SIZE_LETTER;
 exports.PageSizeSchema = PageSizeSchema;
+exports.SCHEMA_FILE_NAMES = SCHEMA_FILE_NAMES;
 exports.SLIDE_SIZE_STANDARD = SLIDE_SIZE_STANDARD;
 exports.SLIDE_SIZE_WIDESCREEN = SLIDE_SIZE_WIDESCREEN;
+exports.UnrecognizedDocumentSchemaError = UnrecognizedDocumentSchemaError;
 exports.colorToRgbHex = colorToRgbHex;
+exports.contentDocumentWithSchema = contentDocumentWithSchema;
+exports.documentFromJson = documentFromJson;
+exports.documentPackageWithSchema = documentPackageWithSchema;
+exports.documentSchemaKindOf = documentSchemaKindOf;
 exports.isContentBlock = isContentBlock;
+exports.layoutDocumentWithSchema = layoutDocumentWithSchema;
 exports.rgbHexToColor = rgbHexToColor;
+exports.schemaUriFor = schemaUriFor;

package/dist/index.d.cts

@@ -46,12 +46,12 @@ type Alignment = z.infer<typeof AlignmentSchema>;
 declare const LayoutFontSchema: z.ZodObject<{
   family: z.ZodString;
   weight: z.ZodEnum<{
-    bold: "bold";
     normal: "normal";
+    bold: "bold";
   }>;
   style: z.ZodEnum<{
-    italic: "italic";
     normal: "normal";
+    italic: "italic";
   }>;
 }, z.core.$strip>;
 type LayoutFont = z.infer<typeof LayoutFontSchema>;
@@ -1264,12 +1264,12 @@ declare const LayoutTextSchema: z.ZodObject<{
   font: z.ZodObject<{
     family: z.ZodString;
     weight: z.ZodEnum<{
-      bold: "bold";
       normal: "normal";
+      bold: "bold";
     }>;
     style: z.ZodEnum<{
-      italic: "italic";
       normal: "normal";
+      italic: "italic";
     }>;
   }, z.core.$strip>;
   sizePt: z.ZodNumber;
@@ -1445,12 +1445,12 @@ declare const LayoutItemSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
   font: z.ZodObject<{
     family: z.ZodString;
     weight: z.ZodEnum<{
-      bold: "bold";
       normal: "normal";
+      bold: "bold";
     }>;
     style: z.ZodEnum<{
-      italic: "italic";
       normal: "normal";
+      italic: "italic";
     }>;
   }, z.core.$strip>;
   sizePt: z.ZodNumber;
@@ -1584,12 +1584,12 @@ declare const LayoutPageSchema: z.ZodObject<{
     font: z.ZodObject<{
       family: z.ZodString;
       weight: z.ZodEnum<{
-        bold: "bold";
         normal: "normal";
+        bold: "bold";
       }>;
       style: z.ZodEnum<{
-        italic: "italic";
         normal: "normal";
+        italic: "italic";
       }>;
     }, z.core.$strip>;
     sizePt: z.ZodNumber;
@@ -1747,12 +1747,12 @@ declare const LayoutDocumentSchema: z.ZodObject<{
       font: z.ZodObject<{
         family: z.ZodString;
         weight: z.ZodEnum<{
-          bold: "bold";
           normal: "normal";
+          bold: "bold";
         }>;
         style: z.ZodEnum<{
-          italic: "italic";
           normal: "normal";
+          italic: "italic";
         }>;
       }, z.core.$strip>;
       sizePt: z.ZodNumber;
@@ -2271,12 +2271,12 @@ declare const DocumentPackageSchema: z.ZodObject<{
         font: z.ZodObject<{
           family: z.ZodString;
           weight: z.ZodEnum<{
-            bold: "bold";
             normal: "normal";
+            bold: "bold";
           }>;
           style: z.ZodEnum<{
-            italic: "italic";
             normal: "normal";
+            italic: "italic";
           }>;
         }, z.core.$strip>;
         sizePt: z.ZodNumber;
@@ -2413,4 +2413,37 @@ declare const DocumentPackageSchema: z.ZodObject<{
 }, z.core.$strip>;
 type DocumentPackage = z.infer<typeof DocumentPackageSchema>;
 //#endregion
-export { Alignment, AlignmentSchema, Box, BoxSchema, COLOR_BLACK, CONTENT_FORMAT_VERSION, Color, ColorSchema, ContentBlock, ContentBlockSchema, ContentCellValue, ContentCellValueSchema, ContentDocument, ContentDocumentSchema, ContentDrawPage, ContentDrawPageSchema, ContentEmbeddedObject, ContentEmbeddedObjectBlock, ContentEmbeddedObjectBlockSchema, ContentEmbeddedObjectKind, ContentEmbeddedObjectSchema, ContentImageBlock, ContentImageBlockSchema, ContentListMembership, ContentListMembershipSchema, ContentPageBreak, ContentPageBreakSchema, ContentParagraph, ContentParagraphSchema, ContentPathPoint, ContentPathPointSchema, ContentPathSegment, ContentPathSegmentSchema, ContentRun, ContentRunSchema, ContentSection, ContentSectionSchema, ContentShape, ContentShapeSchema, ContentSheet, ContentSheetCell, ContentSheetCellSchema, ContentSheetColumn, ContentSheetColumnSchema, ContentSheetImage, ContentSheetImageSchema, ContentSheetPrintRange, ContentSheetPrintRangeSchema, ContentSheetPrintSettings, ContentSheetPrintSettingsSchema, ContentSheetRepeatRange, ContentSheetRepeatRangeSchema, ContentSheetRow, ContentSheetRowSchema, ContentSheetSchema, ContentSlide, ContentSlideSchema, ContentStroke, ContentStrokeSchema, ContentSubpath, ContentSubpathSchema, ContentTable, ContentTableCell, ContentTableCellSchema, ContentTableRow, ContentTableRowSchema, ContentTableSchema, ContentVector, ContentVectorSchema, DEFAULT_LAYOUT_FONT, DOCUMENT_PACKAGE_FORMAT_VERSION, DocumentPackage, DocumentPackageSchema, LAYOUT_FORMAT_VERSION, LayoutDocument, LayoutDocumentSchema, LayoutEllipse, LayoutEllipseSchema, LayoutFont, LayoutFontSchema, LayoutImage, LayoutImageAsset, LayoutImageAssetSchema, LayoutImageSchema, LayoutItem, LayoutItemSchema, LayoutLine, LayoutLineSchema, LayoutLink, LayoutLinkSchema, LayoutMetadata, LayoutMetadataSchema, LayoutPage, LayoutPageSchema, LayoutPath, LayoutPathSchema, LayoutPathSegment, LayoutPathSegmentSchema, LayoutRect, LayoutRectSchema, LayoutSubpath, LayoutSubpathSchema, LayoutText, LayoutTextSchema, Margins, MarginsSchema, PAGE_SIZE_A4, PAGE_SIZE_LETTER, PageSize, PageSizeSchema, SLIDE_SIZE_STANDARD, SLIDE_SIZE_WIDESCREEN, colorToRgbHex, isContentBlock, rgbHexToColor };
+//#region src/schema-io.d.ts
+type DocumentSchemaKind = 'DocumentPackage' | 'ContentDocument' | 'LayoutDocument';
+declare const SCHEMA_FILE_NAMES: Record<DocumentSchemaKind, string>;
+declare function schemaUriFor(kind: DocumentSchemaKind): string;
+declare function documentSchemaKindOf(value: unknown): DocumentSchemaKind | undefined;
+type DocumentPackageJson = DocumentPackage & {
+  readonly $schema: string;
+};
+type ContentDocumentJson = ContentDocument & {
+  readonly $schema: string;
+};
+type LayoutDocumentJson = LayoutDocument & {
+  readonly $schema: string;
+};
+declare function documentPackageWithSchema(value: DocumentPackage): DocumentPackageJson;
+declare function contentDocumentWithSchema(value: ContentDocument): ContentDocumentJson;
+declare function layoutDocumentWithSchema(value: LayoutDocument): LayoutDocumentJson;
+declare class UnrecognizedDocumentSchemaError extends Error {
+  readonly schema: unknown;
+  constructor(schema: unknown);
+}
+type DocumentJsonResult = {
+  kind: 'DocumentPackage';
+  value: DocumentPackage;
+} | {
+  kind: 'ContentDocument';
+  value: ContentDocument;
+} | {
+  kind: 'LayoutDocument';
+  value: LayoutDocument;
+};
+declare function documentFromJson(value: unknown): DocumentJsonResult;
+//#endregion
+export { Alignment, AlignmentSchema, Box, BoxSchema, COLOR_BLACK, CONTENT_FORMAT_VERSION, Color, ColorSchema, ContentBlock, ContentBlockSchema, ContentCellValue, ContentCellValueSchema, ContentDocument, ContentDocumentJson, ContentDocumentSchema, ContentDrawPage, ContentDrawPageSchema, ContentEmbeddedObject, ContentEmbeddedObjectBlock, ContentEmbeddedObjectBlockSchema, ContentEmbeddedObjectKind, ContentEmbeddedObjectSchema, ContentImageBlock, ContentImageBlockSchema, ContentListMembership, ContentListMembershipSchema, ContentPageBreak, ContentPageBreakSchema, ContentParagraph, ContentParagraphSchema, ContentPathPoint, ContentPathPointSchema, ContentPathSegment, ContentPathSegmentSchema, ContentRun, ContentRunSchema, ContentSection, ContentSectionSchema, ContentShape, ContentShapeSchema, ContentSheet, ContentSheetCell, ContentSheetCellSchema, ContentSheetColumn, ContentSheetColumnSchema, ContentSheetImage, ContentSheetImageSchema, ContentSheetPrintRange, ContentSheetPrintRangeSchema, ContentSheetPrintSettings, ContentSheetPrintSettingsSchema, ContentSheetRepeatRange, ContentSheetRepeatRangeSchema, ContentSheetRow, ContentSheetRowSchema, ContentSheetSchema, ContentSlide, ContentSlideSchema, ContentStroke, ContentStrokeSchema, ContentSubpath, ContentSubpathSchema, ContentTable, ContentTableCell, ContentTableCellSchema, ContentTableRow, ContentTableRowSchema, ContentTableSchema, ContentVector, ContentVectorSchema, DEFAULT_LAYOUT_FONT, DOCUMENT_PACKAGE_FORMAT_VERSION, DocumentJsonResult, DocumentPackage, DocumentPackageJson, DocumentPackageSchema, DocumentSchemaKind, LAYOUT_FORMAT_VERSION, LayoutDocument, LayoutDocumentJson, LayoutDocumentSchema, LayoutEllipse, LayoutEllipseSchema, LayoutFont, LayoutFontSchema, LayoutImage, LayoutImageAsset, LayoutImageAssetSchema, LayoutImageSchema, LayoutItem, LayoutItemSchema, LayoutLine, LayoutLineSchema, LayoutLink, LayoutLinkSchema, LayoutMetadata, LayoutMetadataSchema, LayoutPage, LayoutPageSchema, LayoutPath, LayoutPathSchema, LayoutPathSegment, LayoutPathSegmentSchema, LayoutRect, LayoutRectSchema, LayoutSubpath, LayoutSubpathSchema, LayoutText, LayoutTextSchema, Margins, MarginsSchema, PAGE_SIZE_A4, PAGE_SIZE_LETTER, PageSize, PageSizeSchema, SCHEMA_FILE_NAMES, SLIDE_SIZE_STANDARD, SLIDE_SIZE_WIDESCREEN, UnrecognizedDocumentSchemaError, colorToRgbHex, contentDocumentWithSchema, documentFromJson, documentPackageWithSchema, documentSchemaKindOf, isContentBlock, layoutDocumentWithSchema, rgbHexToColor, schemaUriFor };

package/dist/index.d.ts

@@ -46,12 +46,12 @@ type Alignment = z.infer<typeof AlignmentSchema>;
 declare const LayoutFontSchema: z.ZodObject<{
   family: z.ZodString;
   weight: z.ZodEnum<{
-    bold: "bold";
     normal: "normal";
+    bold: "bold";
   }>;
   style: z.ZodEnum<{
-    italic: "italic";
     normal: "normal";
+    italic: "italic";
   }>;
 }, z.core.$strip>;
 type LayoutFont = z.infer<typeof LayoutFontSchema>;
@@ -1264,12 +1264,12 @@ declare const LayoutTextSchema: z.ZodObject<{
   font: z.ZodObject<{
     family: z.ZodString;
     weight: z.ZodEnum<{
-      bold: "bold";
       normal: "normal";
+      bold: "bold";
     }>;
     style: z.ZodEnum<{
-      italic: "italic";
       normal: "normal";
+      italic: "italic";
     }>;
   }, z.core.$strip>;
   sizePt: z.ZodNumber;
@@ -1445,12 +1445,12 @@ declare const LayoutItemSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
   font: z.ZodObject<{
     family: z.ZodString;
     weight: z.ZodEnum<{
-      bold: "bold";
       normal: "normal";
+      bold: "bold";
     }>;
     style: z.ZodEnum<{
-      italic: "italic";
       normal: "normal";
+      italic: "italic";
     }>;
   }, z.core.$strip>;
   sizePt: z.ZodNumber;
@@ -1584,12 +1584,12 @@ declare const LayoutPageSchema: z.ZodObject<{
     font: z.ZodObject<{
       family: z.ZodString;
       weight: z.ZodEnum<{
-        bold: "bold";
         normal: "normal";
+        bold: "bold";
       }>;
       style: z.ZodEnum<{
-        italic: "italic";
         normal: "normal";
+        italic: "italic";
       }>;
     }, z.core.$strip>;
     sizePt: z.ZodNumber;
@@ -1747,12 +1747,12 @@ declare const LayoutDocumentSchema: z.ZodObject<{
       font: z.ZodObject<{
         family: z.ZodString;
         weight: z.ZodEnum<{
-          bold: "bold";
           normal: "normal";
+          bold: "bold";
         }>;
         style: z.ZodEnum<{
-          italic: "italic";
           normal: "normal";
+          italic: "italic";
         }>;
       }, z.core.$strip>;
       sizePt: z.ZodNumber;
@@ -2271,12 +2271,12 @@ declare const DocumentPackageSchema: z.ZodObject<{
         font: z.ZodObject<{
           family: z.ZodString;
           weight: z.ZodEnum<{
-            bold: "bold";
             normal: "normal";
+            bold: "bold";
           }>;
           style: z.ZodEnum<{
-            italic: "italic";
             normal: "normal";
+            italic: "italic";
           }>;
         }, z.core.$strip>;
         sizePt: z.ZodNumber;
@@ -2413,4 +2413,37 @@ declare const DocumentPackageSchema: z.ZodObject<{
 }, z.core.$strip>;
 type DocumentPackage = z.infer<typeof DocumentPackageSchema>;
 //#endregion
-export { Alignment, AlignmentSchema, Box, BoxSchema, COLOR_BLACK, CONTENT_FORMAT_VERSION, Color, ColorSchema, ContentBlock, ContentBlockSchema, ContentCellValue, ContentCellValueSchema, ContentDocument, ContentDocumentSchema, ContentDrawPage, ContentDrawPageSchema, ContentEmbeddedObject, ContentEmbeddedObjectBlock, ContentEmbeddedObjectBlockSchema, ContentEmbeddedObjectKind, ContentEmbeddedObjectSchema, ContentImageBlock, ContentImageBlockSchema, ContentListMembership, ContentListMembershipSchema, ContentPageBreak, ContentPageBreakSchema, ContentParagraph, ContentParagraphSchema, ContentPathPoint, ContentPathPointSchema, ContentPathSegment, ContentPathSegmentSchema, ContentRun, ContentRunSchema, ContentSection, ContentSectionSchema, ContentShape, ContentShapeSchema, ContentSheet, ContentSheetCell, ContentSheetCellSchema, ContentSheetColumn, ContentSheetColumnSchema, ContentSheetImage, ContentSheetImageSchema, ContentSheetPrintRange, ContentSheetPrintRangeSchema, ContentSheetPrintSettings, ContentSheetPrintSettingsSchema, ContentSheetRepeatRange, ContentSheetRepeatRangeSchema, ContentSheetRow, ContentSheetRowSchema, ContentSheetSchema, ContentSlide, ContentSlideSchema, ContentStroke, ContentStrokeSchema, ContentSubpath, ContentSubpathSchema, ContentTable, ContentTableCell, ContentTableCellSchema, ContentTableRow, ContentTableRowSchema, ContentTableSchema, ContentVector, ContentVectorSchema, DEFAULT_LAYOUT_FONT, DOCUMENT_PACKAGE_FORMAT_VERSION, DocumentPackage, DocumentPackageSchema, LAYOUT_FORMAT_VERSION, LayoutDocument, LayoutDocumentSchema, LayoutEllipse, LayoutEllipseSchema, LayoutFont, LayoutFontSchema, LayoutImage, LayoutImageAsset, LayoutImageAssetSchema, LayoutImageSchema, LayoutItem, LayoutItemSchema, LayoutLine, LayoutLineSchema, LayoutLink, LayoutLinkSchema, LayoutMetadata, LayoutMetadataSchema, LayoutPage, LayoutPageSchema, LayoutPath, LayoutPathSchema, LayoutPathSegment, LayoutPathSegmentSchema, LayoutRect, LayoutRectSchema, LayoutSubpath, LayoutSubpathSchema, LayoutText, LayoutTextSchema, Margins, MarginsSchema, PAGE_SIZE_A4, PAGE_SIZE_LETTER, PageSize, PageSizeSchema, SLIDE_SIZE_STANDARD, SLIDE_SIZE_WIDESCREEN, colorToRgbHex, isContentBlock, rgbHexToColor };
+//#region src/schema-io.d.ts
+type DocumentSchemaKind = 'DocumentPackage' | 'ContentDocument' | 'LayoutDocument';
+declare const SCHEMA_FILE_NAMES: Record<DocumentSchemaKind, string>;
+declare function schemaUriFor(kind: DocumentSchemaKind): string;
+declare function documentSchemaKindOf(value: unknown): DocumentSchemaKind | undefined;
+type DocumentPackageJson = DocumentPackage & {
+  readonly $schema: string;
+};
+type ContentDocumentJson = ContentDocument & {
+  readonly $schema: string;
+};
+type LayoutDocumentJson = LayoutDocument & {
+  readonly $schema: string;
+};
+declare function documentPackageWithSchema(value: DocumentPackage): DocumentPackageJson;
+declare function contentDocumentWithSchema(value: ContentDocument): ContentDocumentJson;
+declare function layoutDocumentWithSchema(value: LayoutDocument): LayoutDocumentJson;
+declare class UnrecognizedDocumentSchemaError extends Error {
+  readonly schema: unknown;
+  constructor(schema: unknown);
+}
+type DocumentJsonResult = {
+  kind: 'DocumentPackage';
+  value: DocumentPackage;
+} | {
+  kind: 'ContentDocument';
+  value: ContentDocument;
+} | {
+  kind: 'LayoutDocument';
+  value: LayoutDocument;
+};
+declare function documentFromJson(value: unknown): DocumentJsonResult;
+//#endregion
+export { Alignment, AlignmentSchema, Box, BoxSchema, COLOR_BLACK, CONTENT_FORMAT_VERSION, Color, ColorSchema, ContentBlock, ContentBlockSchema, ContentCellValue, ContentCellValueSchema, ContentDocument, ContentDocumentJson, ContentDocumentSchema, ContentDrawPage, ContentDrawPageSchema, ContentEmbeddedObject, ContentEmbeddedObjectBlock, ContentEmbeddedObjectBlockSchema, ContentEmbeddedObjectKind, ContentEmbeddedObjectSchema, ContentImageBlock, ContentImageBlockSchema, ContentListMembership, ContentListMembershipSchema, ContentPageBreak, ContentPageBreakSchema, ContentParagraph, ContentParagraphSchema, ContentPathPoint, ContentPathPointSchema, ContentPathSegment, ContentPathSegmentSchema, ContentRun, ContentRunSchema, ContentSection, ContentSectionSchema, ContentShape, ContentShapeSchema, ContentSheet, ContentSheetCell, ContentSheetCellSchema, ContentSheetColumn, ContentSheetColumnSchema, ContentSheetImage, ContentSheetImageSchema, ContentSheetPrintRange, ContentSheetPrintRangeSchema, ContentSheetPrintSettings, ContentSheetPrintSettingsSchema, ContentSheetRepeatRange, ContentSheetRepeatRangeSchema, ContentSheetRow, ContentSheetRowSchema, ContentSheetSchema, ContentSlide, ContentSlideSchema, ContentStroke, ContentStrokeSchema, ContentSubpath, ContentSubpathSchema, ContentTable, ContentTableCell, ContentTableCellSchema, ContentTableRow, ContentTableRowSchema, ContentTableSchema, ContentVector, ContentVectorSchema, DEFAULT_LAYOUT_FONT, DOCUMENT_PACKAGE_FORMAT_VERSION, DocumentJsonResult, DocumentPackage, DocumentPackageJson, DocumentPackageSchema, DocumentSchemaKind, LAYOUT_FORMAT_VERSION, LayoutDocument, LayoutDocumentJson, LayoutDocumentSchema, LayoutEllipse, LayoutEllipseSchema, LayoutFont, LayoutFontSchema, LayoutImage, LayoutImageAsset, LayoutImageAssetSchema, LayoutImageSchema, LayoutItem, LayoutItemSchema, LayoutLine, LayoutLineSchema, LayoutLink, LayoutLinkSchema, LayoutMetadata, LayoutMetadataSchema, LayoutPage, LayoutPageSchema, LayoutPath, LayoutPathSchema, LayoutPathSegment, LayoutPathSegmentSchema, LayoutRect, LayoutRectSchema, LayoutSubpath, LayoutSubpathSchema, LayoutText, LayoutTextSchema, Margins, MarginsSchema, PAGE_SIZE_A4, PAGE_SIZE_LETTER, PageSize, PageSizeSchema, SCHEMA_FILE_NAMES, SLIDE_SIZE_STANDARD, SLIDE_SIZE_WIDESCREEN, UnrecognizedDocumentSchemaError, colorToRgbHex, contentDocumentWithSchema, documentFromJson, documentPackageWithSchema, documentSchemaKindOf, isContentBlock, layoutDocumentWithSchema, rgbHexToColor, schemaUriFor };

package/dist/index.js

@@ -140,29 +140,29 @@ const ContentPageBreakSchema = z.object({
 	kind: z.literal("pageBreak"),
 	sourcePath: z.string().optional()
 });
-function isRecord(value) {
+function isRecord$1(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function isContentRun(value) {
-	return isRecord(value) && typeof value.text === "string";
+	return isRecord$1(value) && typeof value.text === "string";
 }
 function isContentTableCell(value) {
-	return isRecord(value) && Array.isArray(value.blocks) && value.blocks.every(isContentBlock);
+	return isRecord$1(value) && Array.isArray(value.blocks) && value.blocks.every(isContentBlock);
 }
 function isContentTableRow(value) {
-	return isRecord(value) && Array.isArray(value.cells) && value.cells.every(isContentTableCell) && (value.heightPt === void 0 || typeof value.heightPt === "number");
+	return isRecord$1(value) && Array.isArray(value.cells) && value.cells.every(isContentTableCell) && (value.heightPt === void 0 || typeof value.heightPt === "number");
 }
 function isContentEmbeddedObjectKind(value) {
 	return value === "formula" || value === "wordprocessing" || value === "presentation" || value === "spreadsheet" || value === "drawing";
 }
 function isContentEmbeddedObject(value) {
-	return isRecord(value) && isContentEmbeddedObjectKind(value.objectKind) && BoxSchema.safeParse(value.frame).success && ContentDocumentSchema.safeParse(value.document).success;
+	return isRecord$1(value) && isContentEmbeddedObjectKind(value.objectKind) && BoxSchema.safeParse(value.frame).success && ContentDocumentSchema.safeParse(value.document).success;
 }
 function isContentEmbeddedObjectBlock(value) {
-	return isRecord(value) && value.kind === "embeddedObject" && isContentEmbeddedObject(value);
+	return isRecord$1(value) && value.kind === "embeddedObject" && isContentEmbeddedObject(value);
 }
 function isContentBlock(value) {
-	if (!isRecord(value)) return false;
+	if (!isRecord$1(value)) return false;
 	const kind = value.kind;
 	if (kind === "paragraph") return Array.isArray(value.runs) && value.runs.every(isContentRun);
 	if (kind === "image") return (value.format === "png" || value.format === "jpeg") && typeof value.base64 === "string" && typeof value.widthPt === "number" && typeof value.heightPt === "number";
@@ -536,4 +536,79 @@ const DocumentPackageSchema = z.object({
 	layout: LayoutDocumentSchema.optional()
 });
 //#endregion
-export { AlignmentSchema, BoxSchema, COLOR_BLACK, CONTENT_FORMAT_VERSION, ColorSchema, ContentBlockSchema, ContentCellValueSchema, ContentDocumentSchema, ContentDrawPageSchema, ContentEmbeddedObjectBlockSchema, ContentEmbeddedObjectSchema, ContentImageBlockSchema, ContentListMembershipSchema, ContentPageBreakSchema, ContentParagraphSchema, ContentPathPointSchema, ContentPathSegmentSchema, ContentRunSchema, ContentSectionSchema, ContentShapeSchema, ContentSheetCellSchema, ContentSheetColumnSchema, ContentSheetImageSchema, ContentSheetPrintRangeSchema, ContentSheetPrintSettingsSchema, ContentSheetRepeatRangeSchema, ContentSheetRowSchema, ContentSheetSchema, ContentSlideSchema, ContentStrokeSchema, ContentSubpathSchema, ContentTableCellSchema, ContentTableRowSchema, ContentTableSchema, ContentVectorSchema, DEFAULT_LAYOUT_FONT, DOCUMENT_PACKAGE_FORMAT_VERSION, DocumentPackageSchema, LAYOUT_FORMAT_VERSION, LayoutDocumentSchema, LayoutEllipseSchema, LayoutFontSchema, LayoutImageAssetSchema, LayoutImageSchema, LayoutItemSchema, LayoutLineSchema, LayoutLinkSchema, LayoutMetadataSchema, LayoutPageSchema, LayoutPathSchema, LayoutPathSegmentSchema, LayoutRectSchema, LayoutSubpathSchema, LayoutTextSchema, MarginsSchema, PAGE_SIZE_A4, PAGE_SIZE_LETTER, PageSizeSchema, SLIDE_SIZE_STANDARD, SLIDE_SIZE_WIDESCREEN, colorToRgbHex, isContentBlock, rgbHexToColor };
+//#region src/schema-io.ts
+const SCHEMA_FILE_NAMES = {
+	DocumentPackage: "document-package.schema.json",
+	ContentDocument: "content-document.schema.json",
+	LayoutDocument: "layout-document.schema.json"
+};
+function schemaUriFor(kind) {
+	return `https://cdn.jsdelivr.net/npm/document-schema.js@1.7.0/schemas/${SCHEMA_FILE_NAMES[kind]}`;
+}
+const SCHEMA_URI_PATTERN = /^https:\/\/cdn\.jsdelivr\.net\/npm\/document-schema\.js@[^/]+\/schemas\/(document-package|content-document|layout-document)\.schema\.json$/;
+function kindForFileStem(stem) {
+	switch (stem) {
+		case "document-package": return "DocumentPackage";
+		case "content-document": return "ContentDocument";
+		case "layout-document": return "LayoutDocument";
+		default: return;
+	}
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function documentSchemaKindOf(value) {
+	if (!isRecord(value)) return void 0;
+	if (!("$schema" in value) || typeof value.$schema !== "string") return void 0;
+	const match = SCHEMA_URI_PATTERN.exec(value.$schema);
+	if (match === null) return void 0;
+	const stem = match[1];
+	if (stem === void 0) return void 0;
+	return kindForFileStem(stem);
+}
+function documentPackageWithSchema(value) {
+	return {
+		$schema: schemaUriFor("DocumentPackage"),
+		...value
+	};
+}
+function contentDocumentWithSchema(value) {
+	return {
+		$schema: schemaUriFor("ContentDocument"),
+		...value
+	};
+}
+function layoutDocumentWithSchema(value) {
+	return {
+		$schema: schemaUriFor("LayoutDocument"),
+		...value
+	};
+}
+var UnrecognizedDocumentSchemaError = class extends Error {
+	schema;
+	constructor(schema) {
+		super(`documentFromJson: value has no recognized "$schema" property (expected one of the three document-schema.js .schema.json URIs; found: ${JSON.stringify(schema)}).`);
+		this.name = "UnrecognizedDocumentSchemaError";
+		this.schema = schema;
+	}
+};
+function documentFromJson(value) {
+	const kind = documentSchemaKindOf(value);
+	if (kind === void 0) throw new UnrecognizedDocumentSchemaError(isRecord(value) ? value.$schema : void 0);
+	switch (kind) {
+		case "DocumentPackage": return {
+			kind,
+			value: DocumentPackageSchema.parse(value)
+		};
+		case "ContentDocument": return {
+			kind,
+			value: ContentDocumentSchema.parse(value)
+		};
+		case "LayoutDocument": return {
+			kind,
+			value: LayoutDocumentSchema.parse(value)
+		};
+	}
+}
+//#endregion
+export { AlignmentSchema, BoxSchema, COLOR_BLACK, CONTENT_FORMAT_VERSION, ColorSchema, ContentBlockSchema, ContentCellValueSchema, ContentDocumentSchema, ContentDrawPageSchema, ContentEmbeddedObjectBlockSchema, ContentEmbeddedObjectSchema, ContentImageBlockSchema, ContentListMembershipSchema, ContentPageBreakSchema, ContentParagraphSchema, ContentPathPointSchema, ContentPathSegmentSchema, ContentRunSchema, ContentSectionSchema, ContentShapeSchema, ContentSheetCellSchema, ContentSheetColumnSchema, ContentSheetImageSchema, ContentSheetPrintRangeSchema, ContentSheetPrintSettingsSchema, ContentSheetRepeatRangeSchema, ContentSheetRowSchema, ContentSheetSchema, ContentSlideSchema, ContentStrokeSchema, ContentSubpathSchema, ContentTableCellSchema, ContentTableRowSchema, ContentTableSchema, ContentVectorSchema, DEFAULT_LAYOUT_FONT, DOCUMENT_PACKAGE_FORMAT_VERSION, DocumentPackageSchema, LAYOUT_FORMAT_VERSION, LayoutDocumentSchema, LayoutEllipseSchema, LayoutFontSchema, LayoutImageAssetSchema, LayoutImageSchema, LayoutItemSchema, LayoutLineSchema, LayoutLinkSchema, LayoutMetadataSchema, LayoutPageSchema, LayoutPathSchema, LayoutPathSegmentSchema, LayoutRectSchema, LayoutSubpathSchema, LayoutTextSchema, MarginsSchema, PAGE_SIZE_A4, PAGE_SIZE_LETTER, PageSizeSchema, SCHEMA_FILE_NAMES, SLIDE_SIZE_STANDARD, SLIDE_SIZE_WIDESCREEN, UnrecognizedDocumentSchemaError, colorToRgbHex, contentDocumentWithSchema, documentFromJson, documentPackageWithSchema, documentSchemaKindOf, isContentBlock, layoutDocumentWithSchema, rgbHexToColor, schemaUriFor };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "document-schema.js",
-  "version": "1.6.0",
+  "version": "1.7.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": {

package/schemas/content-document.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://raw.githubusercontent.com/ExaDev/document-schema.js/0089fb3ebeaa24b412e4ef580e9240084deb276b/schemas/content-document.schema.json",
+  "$id": "https://cdn.jsdelivr.net/npm/document-schema.js@1.7.0/schemas/content-document.schema.json",
   "oneOf": [
     {
       "type": "object",
@@ -930,7 +930,7 @@
                       ]
                     },
                     "document": {
-                      "$ref": "https://raw.githubusercontent.com/ExaDev/document-schema.js/0089fb3ebeaa24b412e4ef580e9240084deb276b/schemas/content-document.schema.json"
+                      "$ref": "https://cdn.jsdelivr.net/npm/document-schema.js@1.7.0/schemas/content-document.schema.json"
                     },
                     "frame": {
                       "$ref": "#/$defs/Box"
@@ -2021,7 +2021,7 @@
           ]
         },
         "document": {
-          "$ref": "https://raw.githubusercontent.com/ExaDev/document-schema.js/0089fb3ebeaa24b412e4ef580e9240084deb276b/schemas/content-document.schema.json"
+          "$ref": "https://cdn.jsdelivr.net/npm/document-schema.js@1.7.0/schemas/content-document.schema.json"
         },
         "frame": {
           "$ref": "#/$defs/Box"

package/schemas/document-package.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://raw.githubusercontent.com/ExaDev/document-schema.js/0089fb3ebeaa24b412e4ef580e9240084deb276b/schemas/document-package.schema.json",
+  "$id": "https://cdn.jsdelivr.net/npm/document-schema.js@1.7.0/schemas/document-package.schema.json",
   "type": "object",
   "properties": {
     "formatVersion": {
@@ -8,10 +8,10 @@
       "const": 1
     },
     "content": {
-      "$ref": "https://raw.githubusercontent.com/ExaDev/document-schema.js/0089fb3ebeaa24b412e4ef580e9240084deb276b/schemas/content-document.schema.json"
+      "$ref": "https://cdn.jsdelivr.net/npm/document-schema.js@1.7.0/schemas/content-document.schema.json"
     },
     "layout": {
-      "$ref": "https://raw.githubusercontent.com/ExaDev/document-schema.js/0089fb3ebeaa24b412e4ef580e9240084deb276b/schemas/layout-document.schema.json"
+      "$ref": "https://cdn.jsdelivr.net/npm/document-schema.js@1.7.0/schemas/layout-document.schema.json"
     }
   },
   "required": [

package/schemas/layout-document.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://raw.githubusercontent.com/ExaDev/document-schema.js/0089fb3ebeaa24b412e4ef580e9240084deb276b/schemas/layout-document.schema.json",
+  "$id": "https://cdn.jsdelivr.net/npm/document-schema.js@1.7.0/schemas/layout-document.schema.json",
   "type": "object",
   "properties": {
     "formatVersion": {