openapi-typesafe 0.0.0 → 1.0.0-rc.1

package/src/domain/openapi/discriminator-conflicts.ts

@@ -0,0 +1,251 @@
+import { admittedPropertyValues, resolveLocalRef } from "./admitted-values.js";
+import { isUnionMember, unionAt } from "./discriminated-union.js";
+import { createRef, escapePointerSegment, parseRefPointer } from "./json-pointer.js";
+
+/**
+ * Discriminator members whose discriminator value their own property does not allow. By the
+ * Discriminator Object rule, a member that no `mapping` entry names has its schema name as the
+ * value, so with a property `enum` (or `const`) that does not list it no value of the member
+ * matches, and where the generator adds the value to the member the property type is `never`.
+ * Each one gets a warning (CODING_PRINCIPLES §8.7).
+ */
+
+export interface DiscriminatorValueConflict {
+  /** The member schema, such as `#/components/schemas/EpisodeObject`. */
+  readonly member: string;
+  /** The schema that has the Discriminator Object. */
+  readonly owner: string;
+  readonly propertyName: string;
+  /** The values the discriminator gives the member: its mapping keys, or its name. */
+  readonly values: readonly string[];
+  /** The values the member's property allows. */
+  readonly allowed: readonly (string | number | boolean | null)[];
+  /** Whether no mapping entry names the member, so its value is its schema name. */
+  readonly isImplicit: boolean;
+}
+
+type JsonObject = Readonly<Record<string, unknown>>;
+
+const COMPONENT_SCHEMAS = "#/components/schemas/";
+
+function isObject(value: unknown): value is JsonObject {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+interface Owner {
+  readonly pointer: string;
+  readonly propertyName: string;
+  readonly mapping: Readonly<Record<string, string>>;
+  readonly memberRefs: readonly string[];
+}
+
+function refsOf(list: unknown): string[] {
+  return (Array.isArray(list) ? list : []).flatMap((item) =>
+    isObject(item) && typeof item.$ref === "string" ? [item.$ref] : [],
+  );
+}
+
+function mappingTarget(target: string): string {
+  return target.startsWith("#") ? target : `${COMPONENT_SCHEMAS}${escapePointerSegment(target)}`;
+}
+
+function ownerAt(node: JsonObject, pointer: () => string): Owner | null {
+  const discriminator = node.discriminator;
+  if (!isObject(discriminator) || typeof discriminator.propertyName !== "string") {
+    return null;
+  }
+  const mapping = isObject(discriminator.mapping)
+    ? (discriminator.mapping as Readonly<Record<string, string>>)
+    : {};
+  const mapped = Object.values(mapping)
+    .filter((t) => typeof t === "string")
+    .map(mappingTarget);
+  const memberRefs = [...refsOf(node.oneOf), ...refsOf(node.anyOf), ...mapped];
+  return { pointer: pointer(), propertyName: discriminator.propertyName, mapping, memberRefs };
+}
+
+/** A node of the document walk; the pointer is built only for the nodes that need it. */
+interface Visit {
+  readonly node: unknown;
+  readonly key: string | null;
+  readonly parent: Visit | null;
+}
+
+function pointerOf(visit: Visit): string {
+  const segments: string[] = [];
+  for (let current: Visit | null = visit; current?.key != null; current = current.parent) {
+    segments.unshift(current.key);
+  }
+  return createRef(segments);
+}
+
+function childrenOf(visit: Visit): Visit[] {
+  const { node } = visit;
+  const entries: [string, unknown][] = Array.isArray(node)
+    ? node.map((item, index) => [String(index), item])
+    : isObject(node)
+      ? Object.entries(node)
+      : [];
+  return entries.map(([key, child]) => ({ node: child, key, parent: visit }));
+}
+
+/**
+ * Every Discriminator Object of the document, depth first, with its pointer. The walk keeps its
+ * own stack, so a document nested past the call stack fails in the transform, as it did before.
+ */
+function ownersIn(document: unknown): Owner[] {
+  const found: Owner[] = [];
+  const stack: Visit[] = [{ node: document, key: null, parent: null }];
+  for (let visit = stack.pop(); visit !== undefined; visit = stack.pop()) {
+    const owner = isObject(visit.node) ? ownerAt(visit.node, () => pointerOf(visit)) : null;
+    if (owner !== null) {
+      found.push(owner);
+    }
+    stack.push(...childrenOf(visit).reverse());
+  }
+  return found;
+}
+
+/** A member and the `$ref`s whose properties its type leaves out (`Omit` of its parents). */
+interface Member {
+  readonly ref: string;
+  readonly skipped: ReadonlySet<string>;
+}
+
+interface Child {
+  readonly ref: string;
+  readonly schema: JsonObject;
+}
+
+/** How the run types an `allOf` of a discriminated union. */
+export interface ConflictOptions {
+  /**
+   * `allof-discriminated-union`: a schema that `allOf`s a union which does not contain it reuses
+   * the union and gets no value, so neither it nor the schemas below it are members.
+   */
+  readonly isUnionReused: boolean;
+}
+
+/** What the search for conflicts reads: the document and its `allOf` children by parent. */
+interface ConflictSearch extends ConflictOptions {
+  readonly document: unknown;
+  readonly children: ReadonlyMap<string, readonly Child[]>;
+}
+
+/** The `allOf` children of the owner that inherit its discriminator. */
+function inheritingChildren(owner: Owner, search: ConflictSearch): readonly Child[] {
+  const children = search.children.get(owner.pointer) ?? [];
+  const resolve = (ref: string) => resolveLocalRef(search.document, ref);
+  const union = search.isUnionReused ? unionAt(owner.pointer, resolve) : undefined;
+  return union === undefined
+    ? children
+    : children.filter((child) => isUnionMember(union, child.ref, resolve));
+}
+
+/** The component schemas whose `allOf` holds a `$ref`, by that `$ref`, in document order. */
+function allOfChildren(document: unknown): Map<string, Child[]> {
+  const schemas = resolveLocalRef(document, "#/components/schemas");
+  const children = new Map<string, Child[]>();
+  for (const [name, schema] of Object.entries(isObject(schemas) ? schemas : {})) {
+    if (!isObject(schema)) {
+      continue;
+    }
+    const child = { ref: `${COMPONENT_SCHEMAS}${escapePointerSegment(name)}`, schema };
+    for (const parent of new Set(refsOf(schema.allOf))) {
+      const siblings = children.get(parent) ?? [];
+      siblings.push(child);
+      children.set(parent, siblings);
+    }
+  }
+  return children;
+}
+
+/** Whether a schema defines a discriminator of the property itself: it is the owner below. */
+function ownsProperty(schema: JsonObject, propertyName: string): boolean {
+  const discriminator = schema.discriminator;
+  return isObject(discriminator) && discriminator.propertyName === propertyName;
+}
+
+/**
+ * Component schemas that inherit the owner through `allOf`, also through a chain
+ * (`Lion: { allOf: [Cat] }`, `Cat: { allOf: [Pet] }`). Each parent on the way is left out of the
+ * member's values, as its type omits the property. A schema with its own discriminator of the
+ * property is a member, but the schemas below it are its own members.
+ */
+function inheritingMembers(owner: Owner, search: ConflictSearch): Member[] {
+  const found: Member[] = [];
+  const visited = new Set([owner.pointer]);
+  const parents: Member[] = [{ ref: owner.pointer, skipped: new Set([owner.pointer]) }];
+  for (let parent = parents.shift(); parent !== undefined; parent = parents.shift()) {
+    const children =
+      parent.ref === owner.pointer
+        ? inheritingChildren(owner, search)
+        : (search.children.get(parent.ref) ?? []);
+    for (const child of children) {
+      if (visited.has(child.ref)) {
+        continue;
+      }
+      visited.add(child.ref);
+      found.push({ ref: child.ref, skipped: parent.skipped });
+      if (!ownsProperty(child.schema, owner.propertyName)) {
+        parents.push({ ref: child.ref, skipped: new Set([...parent.skipped, child.ref]) });
+      }
+    }
+  }
+  return found;
+}
+
+/** The members of an owner, each once: the listed and mapped ones, then the inheriting ones. */
+function membersOf(owner: Owner, search: ConflictSearch): Member[] {
+  const listed = owner.memberRefs.map((ref) => ({ ref, skipped: new Set([owner.pointer]) }));
+  const members = new Map<string, Member>();
+  for (const member of [...listed, ...inheritingMembers(owner, search)]) {
+    if (!members.has(member.ref)) {
+      members.set(member.ref, member);
+    }
+  }
+  return [...members.values()];
+}
+
+function memberValues(owner: Owner, member: string): { values: string[]; isImplicit: boolean } {
+  const values = Object.entries(owner.mapping)
+    .filter(([, target]) => typeof target === "string" && mappingTarget(target) === member)
+    .map(([key]) => key);
+  const name = parseRefPointer(member).pop() ?? "";
+  return values.length > 0 ? { values, isImplicit: false } : { values: [name], isImplicit: true };
+}
+
+function conflictOf(owner: Owner, { ref: member, skipped }: Member, document: unknown) {
+  // The owner's own property is left out of an inheriting member's type (`Omit`).
+  const allowed = admittedPropertyValues(
+    resolveLocalRef(document, member),
+    owner.propertyName,
+    document,
+    skipped,
+  );
+  const { values, isImplicit } = memberValues(owner, member);
+  if (allowed === null || values.some((value) => allowed.has(value))) {
+    return null;
+  }
+  const { pointer, propertyName } = owner;
+  return { member, owner: pointer, propertyName, values, allowed: [...allowed], isImplicit };
+}
+
+/** The conflicts of the document, one per member and value list, in document order. */
+export function findDiscriminatorValueConflicts(
+  document: unknown,
+  options: ConflictOptions = { isUnionReused: false },
+): readonly DiscriminatorValueConflict[] {
+  const conflicts = new Map<string, DiscriminatorValueConflict>();
+  const search = { ...options, document, children: allOfChildren(document) };
+  for (const owner of ownersIn(document)) {
+    for (const member of membersOf(owner, search)) {
+      const conflict = conflictOf(owner, member, document);
+      const key = JSON.stringify([member.ref, conflict?.propertyName, conflict?.values]);
+      if (conflict !== null && !conflicts.has(key)) {
+        conflicts.set(key, conflict);
+      }
+    }
+  }
+  return [...conflicts.values()];
+}

package/src/domain/openapi/document-object.ts

@@ -0,0 +1,12 @@
+import type { ComponentsObject } from "./components-object.js";
+import type { PathsObject } from "./path-item-object.js";
+import type { Schema } from "./schema-object.js";
+
+/** The parts of an OpenAPI document that get a root type (OpenAPI 3.1 §4.8.1). */
+export interface DocumentObject {
+  readonly paths?: PathsObject;
+  readonly webhooks?: PathsObject;
+  readonly components?: ComponentsObject;
+  /** JSON Schema definitions at the document root: named subschemas. */
+  readonly $defs?: Readonly<Record<string, Schema>>;
+}

package/src/domain/openapi/header-object.ts

@@ -0,0 +1,9 @@
+import type { ContentMap } from "./media-type-object.js";
+import type { Schema } from "./schema-object.js";
+
+/** The parts of a Header Object the generator reads (OpenAPI 3.1 §4.8.21). */
+export interface HeaderObject {
+  readonly required?: boolean;
+  readonly schema?: Schema;
+  readonly content?: ContentMap;
+}

package/src/domain/openapi/json-pointer.ts

@@ -0,0 +1,46 @@
+/**
+ * The JSON Pointer of a `$ref` as path segments, with the semantics of Redocly's `parseRef`, which
+ * the original generator used: the part after the first `#/`, split at `/`, each segment unescaped
+ * (`~1` → `/`, `~0` → `~`, then percent-decoding), and empty segments dropped.
+ *
+ * Throws URIError for a malformed percent escape, as the original does.
+ */
+export function parseRefPointer(ref: string): string[] {
+  const [, pointer = ""] = ref.split("#/");
+  return pointer
+    .split("/")
+    .map(unescapePointerSegment)
+    .filter((segment) => segment.length > 0);
+}
+
+function unescapePointerSegment(segment: string): string {
+  return decodeURIComponent(segment.replaceAll("~1", "/").replaceAll("~0", "~"));
+}
+
+/**
+ * Escape one segment for a JSON Pointer in a `$ref` fragment: `~` → `~0`, `/` → `~1`, and `%` →
+ * `%25`, because reading a pointer back percent-decodes it. The original did not escape `%`, so a
+ * name like `50%` threw URIError and `a%2Fb` read back as `a/b` (upstream #2251, #2828).
+ */
+export function escapePointerSegment(segment: string): string {
+  return segment.replaceAll("~", "~0").replaceAll("/", "~1").replaceAll("%", "%25");
+}
+
+/**
+ * Join parts into a local `$ref` (the original `createRef`). Empty parts are skipped. A part that
+ * is itself a `$ref` contributes its segments; any other part is one segment.
+ */
+export function createRef(parts: readonly (string | number | null | undefined)[]): string {
+  let ref = "#";
+  for (const part of parts) {
+    if (part === undefined || part === null || part === "") {
+      continue;
+    }
+    const text = String(part);
+    const segments = parseRefPointer(text);
+    for (const segment of segments.length > 0 ? segments : [text]) {
+      ref += `/${escapePointerSegment(segment)}`;
+    }
+  }
+  return ref;
+}

package/src/domain/openapi/media-type-object.ts

@@ -0,0 +1,26 @@
+import { parseRefPointer } from "./json-pointer.js";
+import type { ReferenceSchema, Schema } from "./schema-object.js";
+
+/** The parts of a Media Type Object the generator reads (OpenAPI 3.2 §4.8.14). */
+export interface MediaTypeObject {
+  /** The complete content. */
+  readonly schema?: Schema;
+  /** Each item of a sequential media type such as `application/jsonl` (OpenAPI 3.2). */
+  readonly itemSchema?: Schema;
+}
+
+/** A `content` map: media type name to a Media Type Object or a `$ref` to one. */
+export type ContentMap = Readonly<Record<string, MediaTypeObject | ReferenceSchema>>;
+
+const COMPONENTS_SEGMENT = "components";
+/** The OpenAPI 3.2 component map of reusable Media Type Objects. */
+export const MEDIA_TYPES_COMPONENT_KIND = "mediaTypes";
+
+/**
+ * Whether a `content` entry's `$ref` points into `components.mediaTypes` (OpenAPI 3.2). Other
+ * `$ref`s in `content` keep the output they had before 3.2 (ADR-020).
+ */
+export function isMediaTypeComponentRef(ref: string): boolean {
+  const [root, kind] = parseRefPointer(ref);
+  return ref.startsWith("#/") && root === COMPONENTS_SEGMENT && kind === MEDIA_TYPES_COMPONENT_KIND;
+}

package/src/domain/openapi/operation-object.ts

@@ -0,0 +1,13 @@
+import type { ParameterOrReference } from "./parameter-object.js";
+import type { RequestBodyObject } from "./request-body-object.js";
+import type { ResponsesObject } from "./response-object.js";
+import type { ReferenceSchema } from "./schema-object.js";
+
+/** The parts of an Operation Object the generator reads (OpenAPI 3.1 §4.8.10). */
+export interface OperationObject {
+  readonly operationId?: string;
+  readonly deprecated?: boolean;
+  readonly parameters?: readonly ParameterOrReference[];
+  readonly requestBody?: RequestBodyObject | ReferenceSchema;
+  readonly responses?: ResponsesObject;
+}

package/src/domain/openapi/parameter-object.ts

@@ -0,0 +1,34 @@
+import type { ContentMap } from "./media-type-object.js";
+import type { ReferenceSchema, Schema } from "./schema-object.js";
+
+export type ParameterLocation = "query" | "header" | "path" | "cookie";
+
+/** Every parameter location, in the order the generated `parameters` type lists them. */
+export const PARAMETER_LOCATIONS: readonly ParameterLocation[] = Object.freeze([
+  "query",
+  "header",
+  "path",
+  "cookie",
+]);
+
+/**
+ * The OpenAPI 3.2 location of a parameter that is the whole query string, described by `content`.
+ * Its type becomes the `query` member of `parameters` (ADR-020).
+ */
+export const QUERYSTRING_LOCATION = "querystring";
+
+/** The parts of a Parameter Object the generator reads (OpenAPI 3.2 §4.8.12). */
+export interface ParameterObject {
+  readonly name: string;
+  readonly in: ParameterLocation | typeof QUERYSTRING_LOCATION;
+  readonly required?: boolean;
+  readonly deprecated?: boolean;
+  /** How the value is serialized; `form` for `in: query` when absent (§4.8.12.4). */
+  readonly style?: string;
+  /** Whether an array or object value is sent as several values; true for `form` when absent. */
+  readonly explode?: boolean;
+  readonly schema?: Schema;
+  readonly content?: ContentMap;
+}
+
+export type ParameterOrReference = ParameterObject | ReferenceSchema;

package/src/domain/openapi/path-item-object.ts

@@ -0,0 +1,70 @@
+import type { OperationObject } from "./operation-object.js";
+import type { ParameterOrReference } from "./parameter-object.js";
+import type { ReferenceSchema } from "./schema-object.js";
+
+/** The methods every generated path item lists, with `?: never` when the document has none. */
+export type HttpMethod = "get" | "put" | "post" | "delete" | "options" | "head" | "patch" | "trace";
+
+/** The operation fields of a path item, in the order the generated types list them. */
+export const HTTP_METHODS: readonly HttpMethod[] = Object.freeze([
+  "get",
+  "put",
+  "post",
+  "delete",
+  "options",
+  "head",
+  "patch",
+  "trace",
+]);
+
+/**
+ * The OpenAPI 3.2 QUERY method. Its member is written only when the path item declares it, so
+ * documents without it keep their output (ADR-020).
+ */
+export const QUERY_METHOD = "query";
+
+/** Every operation field of a path item. */
+export type PathItemMethod = HttpMethod | typeof QUERY_METHOD;
+
+/** The OpenAPI 3.2 path item field for methods other than the fixed fields, by exact name. */
+export const ADDITIONAL_OPERATIONS_KEY = "additionalOperations";
+
+export type OperationEntry = OperationObject | ReferenceSchema;
+
+/** The parts of a Path Item Object the generator reads (OpenAPI 3.2 §4.8.9). */
+export type PathItemObject = {
+  readonly parameters?: readonly ParameterOrReference[];
+  readonly additionalOperations?: Readonly<Record<string, OperationEntry>>;
+} & { readonly [method in PathItemMethod]?: OperationEntry };
+
+/** Path items by URL template (OpenAPI 3.1 §4.8.8); webhooks use the same shape by name. */
+export type PathsObject = Readonly<Record<string, PathItemObject | ReferenceSchema>>;
+
+/** One operation of a path item and the method it is declared under. */
+export interface PathItemOperation {
+  /** A fixed field (`get`, `query`, …) or an `additionalOperations` name (`SUBSCRIBE`). */
+  readonly method: string;
+  readonly operation: OperationEntry;
+  /** JSON Pointer segments from the path item to the operation. */
+  readonly segments: readonly string[];
+}
+
+/**
+ * Every operation of a path item: the fixed methods in output order, then `query`, then
+ * `additionalOperations` in document order.
+ */
+export function pathItemOperations(pathItem: PathItemObject): PathItemOperation[] {
+  const methods: readonly PathItemMethod[] = [...HTTP_METHODS, QUERY_METHOD];
+  const fixed = methods.flatMap((method) => {
+    const operation = pathItem[method];
+    return operation ? [{ method, operation, segments: [method] }] : [];
+  });
+  const additional = Object.entries(pathItem.additionalOperations ?? {}).map(
+    ([method, operation]) => ({
+      method,
+      operation,
+      segments: [ADDITIONAL_OPERATIONS_KEY, method],
+    }),
+  );
+  return [...fixed, ...additional];
+}

package/src/domain/openapi/path-templates.ts

@@ -0,0 +1,31 @@
+/**
+ * The Paths Object rule (OpenAPI 3.1 §4.8.8): "Templated paths with the same hierarchy but
+ * different templated names MUST NOT exist as they are identical." Such paths, `/a/{id}` and
+ * `/a/{name}`, match the same URLs, so a client cannot tell which one a request is for.
+ */
+
+const PATH_PARAMETER_RE = /\{[^}]+\}/g;
+const PATH_PREFIX = "/";
+const UNNAMED_PARAMETER = "{}";
+
+function isObject(value: unknown): value is Readonly<Record<string, unknown>> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * The groups of paths that differ only in the names of their template parameters, each group in
+ * document order, the groups in the order of their first path. Keys that are no path, such as an
+ * `x-` extension, are left out.
+ */
+export function findIdenticalPathTemplates(document: unknown): string[][] {
+  const paths = isObject(document) && isObject(document.paths) ? document.paths : {};
+  const byHierarchy = new Map<string, string[]>();
+  for (const url of Object.keys(paths)) {
+    if (!url.startsWith(PATH_PREFIX) || !url.includes("{")) {
+      continue;
+    }
+    const hierarchy = url.replace(PATH_PARAMETER_RE, UNNAMED_PARAMETER);
+    byHierarchy.set(hierarchy, [...(byHierarchy.get(hierarchy) ?? []), url]);
+  }
+  return [...byHierarchy.values()].filter((urls) => urls.length > 1);
+}

package/src/domain/openapi/request-body-object.ts

@@ -0,0 +1,7 @@
+import type { ContentMap } from "./media-type-object.js";
+
+/** The parts of a Request Body Object the generator reads (OpenAPI 3.1 §4.8.13). */
+export interface RequestBodyObject {
+  readonly required?: boolean;
+  readonly content?: ContentMap;
+}

package/src/domain/openapi/response-object.ts

@@ -0,0 +1,14 @@
+import type { HeaderObject } from "./header-object.js";
+import type { ContentMap } from "./media-type-object.js";
+import type { ReferenceSchema } from "./schema-object.js";
+
+/** The parts of a Response Object the generator reads (OpenAPI 3.1 §4.8.17). */
+export interface ResponseObject {
+  /** Written into the JSDoc of the response's member. */
+  readonly description?: string;
+  readonly headers?: Readonly<Record<string, HeaderObject | ReferenceSchema>>;
+  readonly content?: ContentMap;
+}
+
+/** Responses by status code or `default` (OpenAPI 3.1 §4.8.16). */
+export type ResponsesObject = Readonly<Record<string, ResponseObject | ReferenceSchema>>;

package/src/domain/openapi/schema-object.ts

@@ -0,0 +1,61 @@
+/**
+ * The parts of an OpenAPI / JSON Schema object that the schema transformer reads. Documents are
+ * validated by the loader, so fields are typed as the specification defines them; places where the
+ * original generator tolerates other input check the value at run time.
+ */
+
+export interface ReferenceSchema {
+  readonly $ref: string;
+}
+
+/** A schema: an object, a reference, or a boolean schema (`true` allows anything). */
+export type Schema = SchemaObject | ReferenceSchema | boolean;
+
+export type SchemaTypeName =
+  | "string"
+  | "number"
+  | "integer"
+  | "boolean"
+  | "null"
+  | "array"
+  | "object";
+
+export interface SchemaDiscriminator {
+  /** Optional since OpenAPI 3.2; a discriminator without it adds no property type. */
+  readonly propertyName?: string;
+  readonly mapping?: Readonly<Record<string, string>>;
+}
+
+export interface SchemaObject {
+  readonly type?: SchemaTypeName | readonly (SchemaTypeName | null)[];
+  readonly const?: unknown;
+  readonly enum?: readonly unknown[];
+  readonly nullable?: boolean;
+  readonly format?: string;
+  readonly contentMediaType?: string;
+  readonly contentEncoding?: string;
+  readonly properties?: Readonly<Record<string, Schema>>;
+  readonly required?: readonly string[];
+  readonly additionalProperties?: Schema | Readonly<Record<string, never>>;
+  readonly patternProperties?: Readonly<Record<string, Schema>>;
+  readonly unevaluatedProperties?: Schema | Readonly<Record<string, never>>;
+  readonly $defs?: Readonly<Record<string, SchemaObject>>;
+  readonly items?: Schema | readonly Schema[];
+  readonly prefixItems?: readonly Schema[];
+  readonly unevaluatedItems?: Schema;
+  readonly contains?: Schema;
+  readonly minItems?: number;
+  readonly maxItems?: number;
+  readonly allOf?: readonly Schema[];
+  readonly anyOf?: readonly Schema[];
+  readonly oneOf?: readonly Schema[];
+  readonly discriminator?: SchemaDiscriminator;
+  readonly readOnly?: boolean;
+  readonly writeOnly?: boolean;
+  readonly default?: unknown;
+  readonly deprecated?: boolean;
+  readonly "x-enum-varnames"?: readonly string[];
+  readonly "x-enumNames"?: readonly string[];
+  readonly "x-enum-descriptions"?: readonly string[];
+  readonly "x-enumDescriptions"?: readonly string[];
+}