@jxsuite/schema 0.35.0 → 1.0.0

package/defs/extension-manifest.schema.ts

@@ -0,0 +1,47 @@
+/**
+ * Jx-extension.json manifest schema (specs/extensions.md §4). The manifest is pure data: it
+ * enumerates an extension package's classes and schema fragments; behavior lives in the class
+ * descriptors it points to.
+ */
+
+export const extensionManifestSchema = {
+  additionalProperties: false,
+  description:
+    "Schema for jx-extension.json manifests. Located at the extension package root and " +
+    "exported so hosts can resolve <package>/jx-extension.json through the exports map.",
+  properties: {
+    $schema: { type: "string" },
+    classes: {
+      additionalProperties: { type: "string" },
+      description:
+        "$prototype-visible class name → class descriptor path, relative to the manifest.",
+      type: "object",
+    },
+    description: { description: "One-line description.", type: "string" },
+    name: { description: "Package name; must match package.json.", type: "string" },
+    schemas: {
+      additionalProperties: false,
+      description: "Schema fragments this package contributes, relative to the manifest.",
+      properties: {
+        document: {
+          description: "Document-schema fragment (positions like $paths values).",
+          type: "string",
+        },
+        fields: {
+          description:
+            "Field-union fragment: its $defs members are unioned into the per-project " +
+            "field-schema resource as extension field extras (specs/extensions.md §5.3).",
+          type: "string",
+        },
+        project: {
+          description: "Project-schema fragment (top-level project.json sections).",
+          type: "string",
+        },
+      },
+      type: "object",
+    },
+    title: { description: "Human-readable name for studio surfaces.", type: "string" },
+  },
+  required: ["name"],
+  type: "object",
+} as const;

package/defs/field-schema.schema.ts

@@ -0,0 +1,58 @@
+/**
+ * Field-schema vocabulary (specs/extensions.md §5.3, specs/relationships.md).
+ *
+ * JxFieldSchema is the JSON-Schema-subset shape for a single field inside a section entry schema
+ * (content frontmatter fields, table columns). Recursive positions (`items`, nested `properties`)
+ * reference the well-known **fields resource URI** — a schema resource the generated per-project
+ * entry document re-embeds under the same `$id` with the effective union (core shape +
+ * RelationshipRef + extension extras), shadowing the shipped default by standard compound-document
+ * `$id` resolution. Extension fragments reference the same URI at their field positions.
+ *
+ * (An earlier design used `$dynamicRef`/`$dynamicAnchor` here; ajv restricts `$dynamicAnchor` to
+ * schema-resource roots, which cannot express a non-root recursion unit, so the model uses plain
+ * `$id` indirection instead — verified against ajv 8.20 / 2020-12.)
+ */
+
+/** The well-known $id of the project field-schema union resource. */
+export const PROJECT_FIELDS_SCHEMA_ID = "https://jxsuite.com/schema/project/fields/v2";
+
+/** The well-known $id of the document $paths-value union resource. */
+export const DOCUMENT_PATHS_SCHEMA_ID = "https://jxsuite.com/schema/document/paths/v2";
+
+export const jxFieldSchemaDef = {
+  description:
+    "A single field definition inside a section entry schema — a small, recursive subset of " +
+    "JSON Schema. Recursive positions reference the effective field union via the well-known " +
+    "fields resource $id.",
+  properties: {
+    default: {},
+    description: { type: "string" },
+    enum: { type: "array" },
+    format: { type: "string" },
+    items: { $ref: PROJECT_FIELDS_SCHEMA_ID },
+    properties: {
+      additionalProperties: { $ref: PROJECT_FIELDS_SCHEMA_ID },
+      type: "object",
+    },
+    required: { items: { type: "string" }, type: "array" },
+    type: {
+      enum: ["string", "number", "integer", "boolean", "array", "object"],
+      type: "string",
+    },
+  },
+  required: ["type"],
+  type: "object",
+} as const;
+
+export const relationshipRefSchema = {
+  description:
+    "Relationship reference field: points at a named entry of a referenceable section via " +
+    '"#/<sectionKey>/<name>" (specs/relationships.md). A bare reference is to-one; wrap in an ' +
+    "array field's items for to-many.",
+  properties: {
+    $ref: { pattern: "^#/[A-Za-z][A-Za-z0-9_-]*/[A-Za-z0-9._-]+$", type: "string" },
+    description: { type: "string" },
+  },
+  required: ["$ref"],
+  type: "object",
+} as const;

package/defs/index.ts

@@ -73,6 +73,9 @@ export {
   studioHintsSchema,
 } from "./class-def.schema";
 
-// Content & project
-export { contentTypeDefSchema } from "./content-type-def.schema";
+// Project
 export { projectConfigSchema } from "./project-config.schema";
+
+// Extensions (specs/extensions.md)
+export { extensionManifestSchema } from "./extension-manifest.schema";
+export { jxFieldSchemaDef, relationshipRefSchema } from "./field-schema.schema";

package/defs/project-config.schema.ts

@@ -1,10 +1,11 @@
 export const projectConfigSchema = {
-  additionalProperties: false,
   description:
     "Schema for Jx project.json files. " +
     "A project.json file is the root anchor file for a Jx project, " +
-    "declaring site metadata, default settings, global styles, content types, " +
-    "and build configuration.",
+    "declaring site metadata, default settings, global styles, extensions, " +
+    "and build configuration. Open by design: extension-contributed sections " +
+    "(e.g. `content`) are opaque top-level keys; the generated per-project " +
+    "entry document (project.schema.json) closes the composition.",
   properties: {
     $defs: {
       description: "Global type definitions available to all pages.",
@@ -63,6 +64,12 @@ export const projectConfigSchema = {
       ],
       type: "object",
     },
+    $schema: {
+      description:
+        "Relative path to the generated per-project schema (conventionally " +
+        "./project.schema.json, written by `jx schema`).",
+      type: "string",
+    },
     build: {
       description: "Build configuration.",
       properties: {
@@ -127,13 +134,6 @@ export const projectConfigSchema = {
       },
       type: "object",
     },
-    contentTypes: {
-      additionalProperties: { $ref: "#/$defs/ContentTypeDef" },
-      description:
-        "Content type definitions. Each key is a content type name; " +
-        "the value defines the source directory, frontmatter schema, and element dependencies.",
-      type: "object",
-    },
     copy: {
       additionalProperties: { type: "string" },
       description:
@@ -164,6 +164,14 @@ export const projectConfigSchema = {
       },
       type: "object",
     },
+    extensions: {
+      description:
+        "Extension packages: bare package names (resolved project-first through the package " +
+        "exports map) or relative paths. Each must export jx-extension.json.",
+      examples: [["@jxsuite/parser"]],
+      items: { type: "string" },
+      type: "array",
+    },
     i18n: {
       description: "Internationalization configuration.",
       properties: {

package/extension-manifest.schema.json

@@ -0,0 +1,54 @@
+{
+  "$id": "https://jxsuite.com/schema/extension-manifest/v1",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Jx Extension Manifest",
+  "additionalProperties": false,
+  "description": "Schema for jx-extension.json manifests. Located at the extension package root and exported so hosts can resolve <package>/jx-extension.json through the exports map.",
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "classes": {
+      "additionalProperties": {
+        "type": "string"
+      },
+      "description": "$prototype-visible class name → class descriptor path, relative to the manifest.",
+      "type": "object"
+    },
+    "description": {
+      "description": "One-line description.",
+      "type": "string"
+    },
+    "name": {
+      "description": "Package name; must match package.json.",
+      "type": "string"
+    },
+    "schemas": {
+      "additionalProperties": false,
+      "description": "Schema fragments this package contributes, relative to the manifest.",
+      "properties": {
+        "document": {
+          "description": "Document-schema fragment (positions like $paths values).",
+          "type": "string"
+        },
+        "fields": {
+          "description": "Field-union fragment: its $defs members are unioned into the per-project field-schema resource as extension field extras (specs/extensions.md §5.3).",
+          "type": "string"
+        },
+        "project": {
+          "description": "Project-schema fragment (top-level project.json sections).",
+          "type": "string"
+        }
+      },
+      "type": "object"
+    },
+    "title": {
+      "description": "Human-readable name for studio surfaces.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "name"
+  ],
+  "type": "object"
+}

package/package.json

@@ -1,25 +1,33 @@
 {
   "dependencies": {
-    "@webref/css": "^8.6.1",
+    "@webref/css": "^8.7.0",
     "@webref/elements": "^2.7.1",
-    "@webref/idl": "^3.81.2",
+    "@webref/idl": "^3.81.3",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1"
   },
   "description": "JSON Schema 2020-12 meta-schema generator for Jx documents",
   "exports": {
     ".": "./src/schema.ts",
+    "./extension-registry": "./src/extension-registry.ts",
     "./format-registry": "./src/format-registry.ts",
+    "./project-schemas": "./src/project-schemas.ts",
+    "./validate-project": "./src/validate-project.ts",
     "./types": "./types.ts",
     "./guards": "./src/guards.ts",
     "./parse": "./src/parse.ts",
     "./defs": "./defs/index.ts",
     "./schema.json": "./schema.json",
-    "./project-schema.json": "./project-schema.json"
+    "./project-schema.json": "./project-schema.json",
+    "./extension-manifest.schema.json": "./extension-manifest.schema.json",
+    "./schemas/project.core.schema.json": "./schemas/project.core.schema.json",
+    "./schemas/project.fields.schema.json": "./schemas/project.fields.schema.json",
+    "./schemas/document.paths.schema.json": "./schemas/document.paths.schema.json"
   },
   "files": [
     "src/",
     "defs/",
+    "schemas/",
     "types.ts",
     "*.json",
     "!package.json"
@@ -41,7 +49,7 @@
     "upgrade": "bunx npm-check-updates -u && bun install"
   },
   "type": "module",
-  "version": "0.35.0",
+  "version": "1.0.0",
   "devDependencies": {
     "json-schema-to-ts": "^3.1.1"
   }

package/project-schema.json

@@ -1,49 +1,5 @@
 {
   "$defs": {
-    "ContentTypeDef": {
-      "description": "Content type definition. Defines the source directory, frontmatter schema, and element dependencies.",
-      "properties": {
-        "$elements": {
-          "description": "Custom elements available in markdown directives for this content type.",
-          "items": {
-            "oneOf": [
-              {
-                "properties": {
-                  "$ref": {
-                    "type": "string"
-                  }
-                },
-                "required": [
-                  "$ref"
-                ],
-                "type": "object"
-              },
-              {
-                "type": "string"
-              }
-            ]
-          },
-          "type": "array"
-        },
-        "format": {
-          "description": "Import name of a format class declared in the project imports map (e.g. \"Markdown\", \"Csv\"). When omitted, the format is derived from the source file extension via the format registry. \"json\" is the only built-in.",
-          "type": "string"
-        },
-        "schema": {
-          "description": "JSON Schema for validating frontmatter of content type entries.",
-          "type": "object"
-        },
-        "source": {
-          "description": "Path to the content directory relative to the project root.",
-          "examples": [
-            "./content/blog/",
-            "./content/docs/"
-          ],
-          "type": "string"
-        }
-      },
-      "type": "object"
-    },
     "ImageConfig": {
       "description": "Image optimization configuration for the project.",
       "properties": {
@@ -106,8 +62,7 @@
   },
   "$id": "https://jxsuite.com/schema/project/v1",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "additionalProperties": false,
-  "description": "Schema for Jx project.json files. A project.json file is the root anchor file for a Jx project, declaring site metadata, default settings, global styles, content types, and build configuration.",
+  "description": "Schema for Jx project.json files. A project.json file is the root anchor file for a Jx project, declaring site metadata, default settings, global styles, extensions, and build configuration. Open by design: extension-contributed sections are opaque top-level keys; the generated per-project entry document (project.schema.json) closes the composition.",
   "properties": {
     "$defs": {
       "description": "Global type definitions available to all pages.",
@@ -186,6 +141,10 @@
       ],
       "type": "object"
     },
+    "$schema": {
+      "description": "Relative path to the generated per-project schema (conventionally ./project.schema.json, written by `jx schema`).",
+      "type": "string"
+    },
     "build": {
       "description": "Build configuration.",
       "properties": {
@@ -264,13 +223,6 @@
       },
       "type": "object"
     },
-    "contentTypes": {
-      "additionalProperties": {
-        "$ref": "#/$defs/ContentTypeDef"
-      },
-      "description": "Content type definitions. Each key is a content type name; the value defines the source directory, frontmatter schema, and element dependencies.",
-      "type": "object"
-    },
     "copy": {
       "additionalProperties": {
         "type": "string"
@@ -309,6 +261,18 @@
       },
       "type": "object"
     },
+    "extensions": {
+      "description": "Extension packages: bare package names (resolved project-first through the package exports map) or relative paths. Each must export jx-extension.json.",
+      "examples": [
+        [
+          "@jxsuite/parser"
+        ]
+      ],
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
     "i18n": {
       "description": "Internationalization configuration.",
       "properties": {

package/schema.json

@@ -21651,50 +21651,6 @@
         }
       },
       "type": "object"
-    },
-    "ContentTypeDef": {
-      "description": "Content type definition. Defines the source directory, frontmatter schema, and element dependencies.",
-      "properties": {
-        "$elements": {
-          "description": "Custom elements available in markdown directives for this content type.",
-          "items": {
-            "oneOf": [
-              {
-                "properties": {
-                  "$ref": {
-                    "type": "string"
-                  }
-                },
-                "required": [
-                  "$ref"
-                ],
-                "type": "object"
-              },
-              {
-                "type": "string"
-              }
-            ]
-          },
-          "type": "array"
-        },
-        "format": {
-          "description": "Import name of a format class declared in the project imports map (e.g. \"Markdown\", \"Csv\"). When omitted, the format is derived from the source file extension via the format registry. \"json\" is the only built-in.",
-          "type": "string"
-        },
-        "schema": {
-          "description": "JSON Schema for validating frontmatter of content type entries.",
-          "type": "object"
-        },
-        "source": {
-          "description": "Path to the content directory relative to the project root.",
-          "examples": [
-            "./content/blog/",
-            "./content/docs/"
-          ],
-          "type": "string"
-        }
-      },
-      "type": "object"
     }
   },
   "$id": "https://jxsuite.com/schema/v1",

package/schemas/document.paths.schema.json

@@ -0,0 +1,6 @@
+{
+  "$id": "https://jxsuite.com/schema/document/paths/v2",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "description": "Default $paths-value union for documents. Per-project entry documents override this resource with the union of extension-contributed paths shapes.",
+  "title": "Jx Document Paths Union"
+}