@jsonapi-serde/openapi 0.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2025-present, Ben Scholzen 'DASPRiD'
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,22 @@
+# JSON:API Serde - Server
+
+[![Test](https://github.com/DASPRiD/jsonapi-serde-js/actions/workflows/test.yml/badge.svg)](https://github.com/DASPRiD/jsonapi-serde-js/actions/workflows/test.yml)
+[![codecov](https://codecov.io/gh/DASPRiD/jsonapi-serde-js/graph/badge.svg?token=UfRUzGqiN3)](https://codecov.io/gh/DASPRiD/jsonapi-serde-js)
+
+---
+
+JSON:API Serde is a framework-agnostic [JSON:API](https://jsonapi.org) serialization and deserialization library.
+
+## Documentation
+
+To check out docs, visit [jsonapi-serde.js.org](https://jsonapi-serde.js.org).
+
+## Changelog
+
+Detailed changes for each release are documented in the [CHANGELOG](https://github.com/dasprid/jsonapi-serde-js/blob/main/packages/server/CHANGELOG.md)
+
+## License
+
+[BSD-3-Clause](https://github.com/dasprid/jsonapi-serde-js/blob/main/LICENSE)
+
+Copyright (c) 2025-present, Ben Scholzen 'DASPRiD'

package/dist/body.d.ts

@@ -0,0 +1,11 @@
+import type { AttributesSchema, IncludedTypeSchemas, ParseResourceRequestOptions, RelationshipsSchema } from "@jsonapi-serde/server/request";
+import type { ContentObject } from "openapi3-ts/oas31";
+import type { $ZodType } from "zod/v4/core";
+/**
+ * Generates an OpenAPI 3.1 content object for resource requests based on parser options
+ */
+export declare const buildResourceRequestContentObject: (options: ParseResourceRequestOptions<$ZodType<string> | undefined, string, AttributesSchema | undefined, RelationshipsSchema | undefined, IncludedTypeSchemas | undefined>) => ContentObject;
+/**
+ * Generates an OpenAPI 3.1 content object for relationships requests based on parser options
+ */
+export declare const buildRelationshipsRequestContentObject: (type: string, idSchema?: $ZodType<string | null> | undefined) => ContentObject;

package/dist/body.js

@@ -0,0 +1,96 @@
+import { toJSONSchema } from "zod/v4/core";
+/**
+ * Generates an OpenAPI 3.1 content object for resource requests based on parser options
+ */
+export const buildResourceRequestContentObject = (options) => {
+    const resourceProperties = {
+        type: { type: "string", enum: [options.type] },
+    };
+    const resourceRequired = ["type"];
+    if (options.idSchema) {
+        resourceProperties.id = toJSONSchema(options.idSchema);
+        resourceRequired.push("id");
+    }
+    if (options.attributesSchema) {
+        resourceProperties.attributes = toJSONSchema(options.attributesSchema);
+        resourceRequired.push("attributes");
+    }
+    if (options.relationshipsSchema) {
+        resourceProperties.relationships = toJSONSchema(options.relationshipsSchema);
+        resourceRequired.push("relationships");
+    }
+    const resourceSchema = {
+        type: "object",
+        properties: resourceProperties,
+        required: resourceRequired,
+        additionalProperties: false,
+    };
+    const rootProperties = {
+        data: resourceSchema,
+    };
+    if (options.includedTypeSchemas) {
+        rootProperties.included = {
+            type: "array",
+            items: {
+                oneOf: Object.entries(options.includedTypeSchemas).map(([type, options]) => {
+                    const properties = {
+                        lid: { type: "string" },
+                        type: { type: "string", enum: [type] },
+                    };
+                    const required = ["lid", "type"];
+                    if (options.attributesSchema) {
+                        properties.attributes = toJSONSchema(options.attributesSchema);
+                        required.push("attributes");
+                    }
+                    if (options.relationshipsSchema) {
+                        properties.relationships = toJSONSchema(options.relationshipsSchema);
+                        required.push("relationships");
+                    }
+                    return {
+                        type: "object",
+                        properties: properties,
+                        required: required,
+                    };
+                }),
+            },
+        };
+    }
+    const schema = {
+        type: "object",
+        properties: rootProperties,
+        required: ["data"],
+        additionalProperties: false,
+    };
+    return {
+        "application/vnd.api+json": { schema },
+    };
+};
+/**
+ * Generates an OpenAPI 3.1 content object for relationships requests based on parser options
+ */
+export const buildRelationshipsRequestContentObject = (type, idSchema) => {
+    const schema = {
+        type: "object",
+        properties: {
+            data: {
+                type: "array",
+                items: {
+                    type: "object",
+                    properties: {
+                        type: { type: "string", enum: [type] },
+                        id: idSchema
+                            ? toJSONSchema(idSchema)
+                            : { type: "string", example: "abc" },
+                    },
+                    required: ["id", "type"],
+                    additionalProperties: false,
+                },
+            },
+        },
+        required: ["data"],
+        additionalProperties: false,
+    };
+    return {
+        "application/vnd.api+json": { schema },
+    };
+};

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./body.js";
+export * from "./query.js";
+export * from "./response.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from "./body.js";
+export * from "./query.js";
+export * from "./response.js";

package/dist/query.d.ts

@@ -0,0 +1,7 @@
+import type { ParseQueryOptions, SparseFieldSets } from "@jsonapi-serde/server/request";
+import type { ParameterObject } from "openapi3-ts/oas31";
+import type { $ZodType } from "zod/v4/core";
+/**
+ * Generates OpenAPI 3.1 parameters based on query options
+ */
+export declare const buildQueryParameters: (options: ParseQueryOptions<string | undefined, string | undefined, SparseFieldSets | undefined, $ZodType | undefined, $ZodType | undefined>) => ParameterObject[];

package/dist/query.js

@@ -0,0 +1,93 @@
+import { toJSONSchema } from "zod/v4/core";
+/**
+ * Generates OpenAPI 3.1 parameters based on query options
+ */
+export const buildQueryParameters = (options) => {
+    const parameters = [];
+    if (options.include) {
+        parameters.push({
+            name: "include",
+            in: "query",
+            schema: {
+                type: "array",
+                items: {
+                    type: "string",
+                    enum: [...new Set(options.include.allowed.flatMap(expandDotNotation))],
+                },
+                default: options.include.default,
+            },
+        });
+    }
+    if (options.sort) {
+        parameters.push({
+            name: "include",
+            in: "query",
+            schema: {
+                type: "array",
+                items: {
+                    type: "string",
+                    enum: [
+                        ...options.sort.allowed,
+                        ...options.sort.allowed.map((field) => `-${field}`),
+                    ],
+                },
+                maxItems: options.sort.multiple ? undefined : 1,
+                default: options.sort.default?.map((field) => `${field.order === "desc" ? "-" : ""}${field.field}`),
+            },
+        });
+    }
+    if (options.fields) {
+        parameters.push({
+            name: "fields",
+            in: "query",
+            style: "deepObject",
+            schema: {
+                type: "object",
+                properties: Object.fromEntries(Object.entries(options.fields.allowed).map(([type, fields]) => [
+                    type,
+                    {
+                        type: "string",
+                        description: `Comma-separated list of fields to include for this type. Leave empty to omit all fields. Allowed fields are: ${fields.map((field) => `\`${field}\``).join(", ")}`,
+                    },
+                ])),
+                default: options.fields.default,
+                additionalProperties: false,
+            },
+        });
+    }
+    if (options.filter) {
+        let required = true;
+        if (options.filter._zod.optin === "optional") {
+            required = undefined;
+        }
+        parameters.push({
+            name: "filter",
+            in: "query",
+            style: "deepObject",
+            schema: toJSONSchema(options.filter),
+            required,
+        });
+    }
+    if (options.page) {
+        let required = true;
+        if (options.page._zod.optin === "optional") {
+            required = undefined;
+        }
+        parameters.push({
+            name: "page",
+            in: "query",
+            style: "deepObject",
+            schema: toJSONSchema(options.page),
+            required,
+        });
+    }
+    return parameters;
+};
+const expandDotNotation = (input) => {
+    const parts = input.split(".");
+    const result = [];
+    for (let i = 1; i <= parts.length; ++i) {
+        result.push(parts.slice(0, i).join("."));
+    }
+    return result;
+};

package/dist/response.d.ts

@@ -0,0 +1,48 @@
+import type { ResponseObject, SchemaObject } from "openapi3-ts/oas31";
+export type Cardinality = "one" | "one_nullable" | "many";
+export type RelationshipDefinition = {
+    name: string;
+    type: string;
+    cardinality: Cardinality;
+};
+export type MetaSchemaObject = SchemaObject & {
+    type: "object";
+};
+export type LinkSchemaObjects = Record<string, SchemaObject>;
+export type BuildResourceSchemaObjectOptions = {
+    type: string;
+    id?: SchemaObject;
+    attributes?: SchemaObject;
+    relationships?: RelationshipDefinition[];
+    meta?: MetaSchemaObject;
+    links?: LinkSchemaObjects;
+    title?: string;
+    description?: string;
+};
+export declare const linkStringSchemaObject: SchemaObject;
+export declare const linkObjectSchemaObject: SchemaObject;
+export declare const linkSchemaObject: SchemaObject;
+/**
+ * Builds an OpenAPI 3.1 SchemaObject for a resource, including id, type, attributes, relationships, meta, and links
+ */
+export declare const buildResourceSchemaObject: (options: BuildResourceSchemaObjectOptions) => SchemaObject;
+type BuildDataResponseObjectOptions = {
+    resourceSchema: SchemaObject;
+    cardinality: Cardinality;
+    meta?: MetaSchemaObject;
+    description?: string;
+    links?: LinkSchemaObjects;
+    included?: SchemaObject[];
+};
+/**
+ * Builds an OpenAPI 3.1 ResponseObject for data responses including data, meta, links, and included
+ */
+export declare const buildDataResponseObject: (options: BuildDataResponseObjectOptions) => ResponseObject;
+export type BuildErrorResponseObjectOptions = {
+    description: string;
+};
+/**
+ * Builds an OpenAPI 3.1 ResponseObject for error responses containing an errors array
+ */
+export declare const buildErrorResponseObject: (options: BuildErrorResponseObjectOptions) => ResponseObject;
+export {};

package/dist/response.js

@@ -0,0 +1,177 @@
+export const linkStringSchemaObject = { type: "string", format: "uri-reference" };
+export const linkObjectSchemaObject = {
+    type: "object",
+    properties: {
+        href: { type: "string", format: "uri-reference" },
+        rel: { type: "string" },
+        describedby: { type: "string" },
+        title: { type: "string" },
+        type: { type: "string" },
+        hreflang: { type: "string" },
+        meta: {
+            type: "object",
+        },
+    },
+    required: ["href"],
+};
+export const linkSchemaObject = {
+    oneOf: [linkStringSchemaObject, linkObjectSchemaObject],
+};
+/**
+ * Builds an OpenAPI 3.1 SchemaObject for a resource, including id, type, attributes, relationships, meta, and links
+ */
+export const buildResourceSchemaObject = (options) => {
+    const properties = {
+        id: options.id ?? {
+            type: "string",
+            example: "abc",
+        },
+        type: {
+            type: "string",
+            enum: [options.type],
+        },
+    };
+    const required = ["id", "type"];
+    if (options.attributes) {
+        properties.attributes = options.attributes;
+        required.push("attributes");
+    }
+    if (options.relationships) {
+        properties.relationships = {
+            type: "object",
+            properties: Object.fromEntries(options.relationships.map((relationship) => {
+                const resourceIdentifierSchema = {
+                    type: "object",
+                    properties: {
+                        id: { type: "string", example: "12345" },
+                        type: { type: "string", enum: [relationship.type] },
+                    },
+                    required: ["id", "type"],
+                };
+                const schemaObject = {
+                    type: "object",
+                    properties: {
+                        data: expandSchema(resourceIdentifierSchema, relationship.cardinality),
+                    },
+                    required: ["data"],
+                };
+                return [relationship.name, schemaObject];
+            })),
+            required: options.relationships.map((relationship) => relationship.name),
+        };
+        required.push("relationships");
+    }
+    if (options.links) {
+        properties.links = buildLinksSchemaObject(options.links);
+        required.push("links");
+    }
+    if (options.meta) {
+        properties.meta = options.meta;
+        required.push("meta");
+    }
+    return {
+        type: "object",
+        properties,
+        required,
+        title: options.title,
+        description: options.description,
+    };
+};
+/**
+ * Builds an OpenAPI 3.1 ResponseObject for data responses including data, meta, links, and included
+ */
+export const buildDataResponseObject = (options) => {
+    const properties = {
+        data: expandSchema(options.resourceSchema, options.cardinality),
+    };
+    const required = ["data"];
+    if (options.meta) {
+        properties.meta = options.meta;
+        required.push("meta");
+    }
+    if (options.links) {
+        properties.links = buildLinksSchemaObject(options.links);
+    }
+    if (options.included) {
+        properties.included = {
+            type: "array",
+            items: {
+                oneOf: options.included,
+            },
+        };
+    }
+    return {
+        description: options.description ?? "OK",
+        content: {
+            "application/vnd.api+json": {
+                schema: {
+                    type: "object",
+                    properties,
+                    required,
+                },
+            },
+        },
+    };
+};
+/**
+ * Builds an OpenAPI 3.1 ResponseObject for error responses containing an errors array
+ */
+export const buildErrorResponseObject = (options) => ({
+    description: options.description,
+    content: {
+        "application/vnd.api+json": {
+            schema: {
+                type: "object",
+                properties: {
+                    errors: {
+                        type: "array",
+                        minLength: 1,
+                        items: {
+                            type: "object",
+                            properties: {
+                                status: { type: "string", description: "HTTP status code" },
+                                code: { type: "string" },
+                                title: { type: "string" },
+                                detail: { type: "string" },
+                                source: {
+                                    type: "object",
+                                    properties: {
+                                        pointer: { type: "string" },
+                                        parameter: { type: "string" },
+                                        header: { type: "string" },
+                                    },
+                                },
+                            },
+                            required: ["status"],
+                        },
+                    },
+                },
+                required: ["errors"],
+            },
+        },
+    },
+});
+const buildLinksSchemaObject = (links) => ({
+    type: "object",
+    properties: Object.fromEntries(Object.entries(links).map(([name, schemaObject]) => [
+        name,
+        {
+            oneOf: [schemaObject, { type: "null" }],
+        },
+    ])),
+});
+const expandSchema = (schema, cardinality) => {
+    switch (cardinality) {
+        case "one":
+            return schema;
+        case "one_nullable":
+            return {
+                oneOf: [schema, { type: "null" }],
+            };
+        case "many":
+            return {
+                type: "array",
+                items: schema,
+            };
+    }
+};

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@jsonapi-serde/openapi",
+  "version": "0.0.0",
+  "description": "OpenAPI schema generation for JSON:API serde",
+  "type": "module",
+  "author": "Ben Scholzen 'DASPRiD'",
+  "license": "BSD-3-Clause",
+  "keywords": [
+    "jsonapi",
+    "typescript",
+    "zod",
+    "openapi"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dasprid/jsonapi-serde-js.git"
+  },
+  "files": [
+    "dist/**/*"
+  ],
+  "exports": {
+    "./index": {
+      "types": [
+        "./dist/index/index.d.ts",
+        "./src/index/index.ts"
+      ],
+      "default": "./dist/index/index.js"
+    }
+  },
+  "devDependencies": {
+    "openapi3-ts": "^4.4.0",
+    "zod": "^3.25.42",
+    "@jsonapi-serde/server": "0.0.0"
+  },
+  "peerDependencies": {
+    "openapi3-ts": "^4.4.0",
+    "zod": "^3.25.42",
+    "@jsonapi-serde/server": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "tsx --test --test-reporter=spec",
+    "typecheck": "tsc --noEmit",
+    "ci:test": "c8 --reporter=lcov pnpm test"
+  }
+}