@dropsh/plugin-jsonapi-schema 0.5.1

package/LICENSE

@@ -0,0 +1,51 @@
+drupal-cli is dual-licensed. You may use this software under the terms of
+either the MIT License or the GNU General Public License version 2 or any
+later version, at your option.
+
+SPDX-License-Identifier: (MIT OR GPL-2.0-or-later)
+
+================================================================================
+MIT License
+================================================================================
+
+Copyright (c) 2026 Christian Wiedemann
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+================================================================================
+GNU General Public License, version 2 or later
+================================================================================
+
+The full text of the GNU GPL v2 is available at:
+  https://www.gnu.org/licenses/old-licenses/gpl-2.0.txt
+
+The full text of any later GPL version is available at:
+  https://www.gnu.org/licenses/
+
+Copyright (C) 2026 Christian Wiedemann
+
+This program is free software; you can redistribute it and/or modify it under
+the terms of the GNU General Public License as published by the Free Software
+Foundation; either version 2 of the License, or (at your option) any later
+version.
+
+This program is distributed in the hope that it will be useful, but WITHOUT
+ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
+details.

package/README.md

@@ -0,0 +1,86 @@
+# @dropsh/plugin-jsonapi-schema
+
+Authoritative JSON:API write-schema source for [dropsh](https://github.com/pen-drop/dropsh),
+the entity-agnostic CLI for Drupal 11 JSON:API.
+
+dropsh works without this plugin. By default it derives a shallow schema from
+JSON:API sample records, which is enough to discover field names but does not
+know Drupal's required fields, formats, or constraints.
+
+With this plugin installed, `dropsh schema` reads the **authoritative** schema
+from Drupal's [`jsonapi_schema`](https://www.drupal.org/project/jsonapi_schema)
+module. The generated schema carries `required` fields, `maxLength`, and
+`format` constraints, so client-side validation in `create` / `update` catches
+invalid payloads before they are sent to Drupal.
+
+## Why not `schemata`?
+
+The older `@dropsh/plugin-schemata` targets the `schemata_json_schema` module,
+whose `/schemata/{entity}/{bundle}` endpoint returns **HTTP 500 on Drupal 11 /
+PHP 8.4**. `jsonapi_schema` is actively maintained, supports Drupal 10.1+/11,
+and serves its schema routes under the JSON:API prefix (`/jsonapi/*`), so it
+authenticates with the same credentials as every other dropsh request.
+
+Unlike `schemata`, this plugin never swallows a broken endpoint silently: a
+missing module (404) or a broken endpoint (5xx / unparseable body) both fall
+back to the heuristic schema **with a visible warning** explaining why.
+
+## Install
+
+```bash
+pnpm add @dropsh/plugin-jsonapi-schema
+```
+
+`dropsh` is a peer dependency.
+
+## Usage
+
+```js
+import { jsonapiSchemaPlugin } from "@dropsh/plugin-jsonapi-schema";
+
+export default {
+  site: { base_url: "https://my-drupal.example.com", jsonapi_prefix: "/jsonapi" },
+  plugins: [jsonapiSchemaPlugin()],
+};
+```
+
+```bash
+dropsh schema node/article --for=create
+```
+
+The output carries `x-dropsh-source: "jsonapi-schema"` when the authoritative
+schema was used (vs `"heuristic"` / `"heuristic-empty"` for the sample-derived
+fallback).
+
+## Required Drupal module
+
+- [`jsonapi_schema`](https://www.drupal.org/project/jsonapi_schema) (`^1.0`)
+
+Install and enable it on the Drupal site:
+
+```bash
+composer require drupal/jsonapi_schema
+drush en jsonapi_schema
+```
+
+**Authentication note:** the schema routes (`…/resource/schema`) do not declare
+`_auth`, so Drupal core `basic_auth` (which is `global: false`) cannot
+authenticate them — an authenticated basic request is rejected with 403 (the
+same limitation the `schemata` module has). Use an auth provider that is
+registered globally, such as OAuth2 Bearer via `simple_oauth` (see
+`@dropsh/plugin-oauth2`), or grant the anonymous role access to the routes if
+your schemas are non-sensitive.
+
+## How it works
+
+The plugin fetches the **resource-object** schema at
+`{jsonapi_prefix}/{entity}/{bundle}/resource/schema`, inlines its local
+`#/definitions` graph, drops the external `https://jsonapi.org/schema#` `$ref`
+(which Ajv cannot fetch), and wraps the resource object as the `data` member of
+a JSON:API document envelope — the exact shape a create/update payload must
+satisfy. dropsh's operation transform then tailors `required` per operation
+(`id` is stripped for create; `type`/`id` are required for update).
+
+## License
+
+MIT OR GPL-2.0-or-later

package/dist/plugins/jsonapi-schema/src/index.js

@@ -0,0 +1,50 @@
+import { HttpError } from "dropsh/plugin";
+import { buildWriteSchema, fetchJsonapiSchema, JSONAPI_SCHEMA_MISS } from "./jsonapi-schema.js";
+/**
+ * Authoritative JSON:API write-schema source backed by the Drupal
+ * `jsonapi_schema` module (works on Drupal 10.1+/11 + PHP 8.4, unlike the
+ * dead `schemata_json_schema` endpoint which 500s there).
+ *
+ * Outcomes are distinguished instead of collapsed into one silent fallback:
+ * - 200 → the derived write schema replaces the heuristic base.
+ * - 404 → the module/route is absent; fall back to the heuristic base **and**
+ *   warn why (so the user knows the constraint-bearing schema is missing).
+ * - any other status / unparseable body → the endpoint is broken; fall back to
+ *   the heuristic base **and** warn visibly. Never swallowed silently.
+ */
+export function jsonapiSchemaPlugin() {
+    return {
+        id: "jsonapi-schema",
+        requiredModules: ["jsonapi_schema"],
+        async extendSchema(entityType, bundle, baseSchema, ctx) {
+            const target = `${entityType}/${bundle}`;
+            try {
+                const raw = await fetchJsonapiSchema({
+                    http: ctx.http,
+                    auth: ctx.auth,
+                    baseUrl: ctx.baseUrl,
+                    jsonapiPrefix: ctx.jsonapiPrefix ?? "/jsonapi",
+                    entity: entityType,
+                    bundle,
+                });
+                if (raw === JSONAPI_SCHEMA_MISS) {
+                    ctx.warn?.(`warning: jsonapi_schema module not enabled (no schema route for ${target}); ` +
+                        `falling back to the heuristic schema (no required fields, no constraints)`);
+                    return baseSchema;
+                }
+                return buildWriteSchema(raw);
+            }
+            catch (err) {
+                if (err instanceof HttpError) {
+                    ctx.warn?.(`warning: jsonapi_schema endpoint for ${target} is broken (HTTP ${err.status}); ` +
+                        `falling back to the heuristic schema`);
+                }
+                else {
+                    ctx.warn?.(`warning: jsonapi_schema endpoint for ${target} returned an unusable schema ` +
+                        `(${err.message}); falling back to the heuristic schema`);
+                }
+                return baseSchema;
+            }
+        },
+    };
+}

package/dist/plugins/jsonapi-schema/src/jsonapi-schema.js

@@ -0,0 +1,114 @@
+import { HttpError } from "dropsh/plugin";
+/** Sentinel returned when the jsonapi_schema route is absent (HTTP 404). */
+export const JSONAPI_SCHEMA_MISS = Symbol("JSONAPI_SCHEMA_MISS");
+/**
+ * Fetch the resource-object schema for a bundle from the jsonapi_schema module.
+ *
+ * Route (dynamic, registered by jsonapi_schema): the resource-object schema
+ * lives at `{jsonapiPrefix}/{entity}/{bundle}/resource/schema`. It describes a
+ * single JSON:API resource object (type + attributes + relationships), which is
+ * exactly what a create/update payload's `data` member must satisfy.
+ *
+ * Returns the parsed schema on 200, {@link JSONAPI_SCHEMA_MISS} on 404 (module
+ * or route absent), and throws on any other HTTP status (a broken endpoint must
+ * be surfaced, never silently swallowed) or an unparseable body.
+ */
+export async function fetchJsonapiSchema(deps) {
+    const base = deps.baseUrl.replace(/\/+$/, "");
+    const prefix = `/${deps.jsonapiPrefix.replace(/^\/+|\/+$/g, "")}`;
+    const url = `${base}${prefix}/${deps.entity}/${deps.bundle}/resource/schema`;
+    const req = await deps.auth.apply({
+        method: "GET",
+        url,
+        headers: { Accept: "application/json" },
+    });
+    let res;
+    try {
+        res = await deps.http.send(req);
+    }
+    catch (err) {
+        if (err instanceof HttpError && err.status === 404)
+            return JSONAPI_SCHEMA_MISS;
+        throw err;
+    }
+    return JSON.parse(res.body);
+}
+const ABSOLUTE_REF = /^https?:\/\//;
+/**
+ * Strip hyper-schema noise that Ajv either ignores or cannot compile:
+ * `links` (JSON hyper-schema; carries absolute `$ref`s to related routes),
+ * document identity keywords (`$schema`, `$id`), and any leftover absolute
+ * `$ref` (neutralised to an always-true `{}` so compilation never fails).
+ */
+function sanitize(node) {
+    if (Array.isArray(node))
+        return node.map(sanitize);
+    if (node === null || typeof node !== "object")
+        return node;
+    if (typeof node.$ref === "string" && ABSOLUTE_REF.test(node.$ref))
+        return {};
+    const out = {};
+    for (const [key, value] of Object.entries(node)) {
+        if (key === "links" || key === "$schema" || key === "$id")
+            continue;
+        out[key] = sanitize(value);
+    }
+    return out;
+}
+/** Resolve a single-level local `#/definitions/X` reference against `defs`. */
+function resolveLocal(node, defs) {
+    if (node && typeof node === "object" && typeof node.$ref === "string") {
+        const m = /^#\/definitions\/(.+)$/.exec(node.$ref);
+        const name = m?.[1];
+        if (name && defs && defs[name] !== undefined)
+            return defs[name];
+    }
+    return node;
+}
+/**
+ * Transform a jsonapi_schema resource-object schema into a JSON Schema that
+ * validates a dropsh create/update payload — a JSON:API document envelope
+ * `{ data: { type, id, attributes, relationships } }`.
+ *
+ * The module emits `{ allOf: [ { properties: { type, attributes, relationships }
+ * (local $refs) }, { $ref: "https://jsonapi.org/schema#/definitions/resource" } ],
+ * definitions: {...} }`. We inline the local definitions, drop the external
+ * jsonapi.org `$ref` (Ajv cannot fetch it), and wrap the resource object as the
+ * `data` member. dropsh's `toOperationVariant` later tailors `required` per
+ * operation, so we only assert the resource `type` here.
+ */
+export function buildWriteSchema(resourceSchema) {
+    const root = resourceSchema;
+    if (root === null || typeof root !== "object") {
+        throw new Error("jsonapi_schema response is not an object");
+    }
+    const defs = root.definitions ?? {};
+    const allOf = Array.isArray(root.allOf) ? root.allOf : [];
+    const resourceMember = allOf.find((m) => m && typeof m === "object" && m.properties && typeof m.properties === "object");
+    const props = resourceMember?.properties;
+    if (!props || (props.attributes === undefined && props.type === undefined)) {
+        throw new Error("jsonapi_schema response has no resource-object properties");
+    }
+    const dataProperties = {
+        type: sanitize(resolveLocal(props.type ?? { type: "string" }, defs)),
+        id: { type: "string" },
+    };
+    if (props.attributes !== undefined) {
+        dataProperties.attributes = sanitize(resolveLocal(props.attributes, defs));
+    }
+    if (props.relationships !== undefined) {
+        dataProperties.relationships = sanitize(resolveLocal(props.relationships, defs));
+    }
+    return {
+        $schema: "http://json-schema.org/draft-07/schema#",
+        type: "object",
+        properties: {
+            data: {
+                type: "object",
+                properties: dataProperties,
+                required: ["type"],
+            },
+        },
+        required: ["data"],
+    };
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@dropsh/plugin-jsonapi-schema",
+  "version": "0.5.1",
+  "type": "module",
+  "main": "./dist/plugins/jsonapi-schema/src/index.js",
+  "exports": {
+    ".": "./dist/plugins/jsonapi-schema/src/index.js"
+  },
+  "files": [
+    "dist/plugins/jsonapi-schema/src",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "dropsh": "*"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "vitest": "^4.1.8",
+    "dropsh": "0.5.1"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run --passWithNoTests",
+    "typecheck": "tsc --noEmit"
+  }
+}