@obsidiane/meridiane 2.0.13 → 3.0.0

package/src/generators/bridge/write-bridge-files.js

@@ -2,32 +2,16 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-import { readJson, writeJsonIfChanged } from '../../infrastructure/json.js';
+import { ensureCleanDir, readJson, writeJson } from '../../infrastructure/files.js';
 
 const currentDir = path.dirname(fileURLToPath(import.meta.url));
 const packageRoot = path.resolve(currentDir, '../../..');
 const bridgeTemplateDir = path.join(packageRoot, 'templates', 'angular-bridge');
 
-export async function writeBridgeFiles({
-  projectDir,
-  libName,
-  packageName,
-  version,
-  projectReadmePath,
-  debug,
-  log,
-}) {
-  if (debug) {
-    log?.debug?.('[meridiane] generate lib', {
-      libName,
-      packageName,
-      version,
-      targetDir: projectDir,
-    });
-  }
+export async function writeBridgeFiles({ projectDir, libName, packageName, version, projectReadmePath, log }) {
+  log.debug('[meridiane] generate lib', { libName, packageName, version, targetDir: projectDir });
 
-  await fs.rm(projectDir, { recursive: true, force: true });
-  await fs.mkdir(projectDir, { recursive: true });
+  await ensureCleanDir(projectDir);
   await fs.cp(bridgeTemplateDir, projectDir, { recursive: true });
 
   await replacePlaceholders(projectDir, {
@@ -39,9 +23,9 @@ export async function writeBridgeFiles({
   const packageJson = await readJson(packageJsonPath);
   packageJson.name = packageName;
   packageJson.version = version;
-  await writeJsonIfChanged(packageJsonPath, packageJson);
+  await writeJson(packageJsonPath, packageJson);
 
-  await appendProjectReadme(path.join(projectDir, 'README.md'), projectReadmePath, debug, log);
+  await appendProjectReadme(path.join(projectDir, 'README.md'), projectReadmePath, log);
 }
 
 export async function configureBridgeOutput({ projectDir, distRoot, libName, log }) {
@@ -50,8 +34,8 @@ export async function configureBridgeOutput({ projectDir, distRoot, libName, log
   const outputDir = path.join(distRoot, libName);
 
   ngPackage.dest = path.relative(projectDir, outputDir).split(path.sep).join('/');
-  await writeJsonIfChanged(ngPackagePath, ngPackage);
-  log?.debug?.('ng-package.json dest overridden', { dest: ngPackage.dest });
+  await writeJson(ngPackagePath, ngPackage);
+  log.debug('ng-package.json dest overridden', { dest: ngPackage.dest });
 }
 
 async function replacePlaceholders(directory, placeholders) {
@@ -72,23 +56,21 @@ async function replacePlaceholders(directory, placeholders) {
   }
 }
 
-async function appendProjectReadme(targetPath, sourcePath, debug, log) {
-  if (!sourcePath) return;
-
+async function appendProjectReadme(targetPath, sourcePath, log) {
   const projectReadme = await readText(sourcePath);
   if (!projectReadme?.trim()) return;
 
   const bridgeReadme = await readText(targetPath);
   if (!bridgeReadme?.trim()) {
     await fs.writeFile(targetPath, projectReadme);
-    if (debug) log?.debug?.('[meridiane] project README copied', { source: sourcePath });
+    log.debug('[meridiane] project README copied', { source: sourcePath });
     return;
   }
 
   const combinedReadme =
     `${bridgeReadme.trimEnd()}\n\n---\n\n## Documentation du projet\n\n${projectReadme.trimStart()}`;
   await fs.writeFile(targetPath, combinedReadme);
-  if (debug) log?.debug?.('[meridiane] project README appended', { source: sourcePath });
+  log.debug('[meridiane] project README appended', { source: sourcePath });
 }
 
 async function readText(filePath) {

package/src/generators/models/interface-schema.js

@@ -1,4 +1,4 @@
-import {hasOwn, isObject, mergeAllOf, schemaNameFromRef} from './schema-utils.js';
+import {hasOwn, isObject, schemaNameFromRef} from './schema-utils.js';
 
 function hasPropertyConflict(left, right) {
   return Object.keys(right).some((propertyName) => hasOwn(left, propertyName));
@@ -55,29 +55,12 @@ export function collectInterfaceTypeNames(schemas, schemaNames, typeNames) {
 
 /**
  * Flattens object-only allOf parts and keeps component references as interface
- * inheritance. Unsafe or conflicting compositions fall back to a type alias.
+ * inheritance (Hydra base schemas are covered by `Item`). Unsafe or conflicting
+ * compositions fall back to a type alias.
  */
 export function resolveInterfaceSchema(raw, currentTypeName, typeNames, interfaceTypeNames) {
   if (!raw?.allOf) return {schema: raw, extendsTypes: [], compatible: true};
 
-  const merged = mergeAllOf(raw.allOf);
-  if (merged) {
-    const ownProperties = raw.properties ?? {};
-    if (hasPropertyConflict(merged.properties, ownProperties)) {
-      return {schema: raw, extendsTypes: [], compatible: false};
-    }
-
-    return {
-      schema: {
-        ...merged,
-        properties: {...ownProperties, ...merged.properties},
-        required: [...new Set([...(raw.required ?? []), ...merged.required])],
-      },
-      extendsTypes: [],
-      compatible: true,
-    };
-  }
-
   const properties = {...(raw.properties ?? {})};
   const required = new Set(raw.required ?? []);
   const inheritedTypes = new Set();

package/src/generators/models/model-selection.js

@@ -1,42 +1,16 @@
-import {
-  canonicalizeMediaType,
-  collectUsedSchemasForMediaType,
-  expandWithSchemaDependencies,
-} from './oas-contract.js';
+import {expandWithSchemaDependencies} from './oas-contract.js';
 import {
   baseTsNameFromBasePath,
-  formatSuffixToken,
   groupTsNameFromGroupPath,
   parseOpenApiSchemaName,
 } from './oas-schema-name.js';
 import {sanitizeTypeName} from './utils.js';
 
-export const DEFAULT_MODEL_FORMAT = 'application/ld+json';
-
-function normalizeFormats(values) {
-  const formats = [];
-  for (const value of Array.isArray(values) ? values : []) {
-    const format = canonicalizeMediaType(value);
-    if (format && !formats.includes(format)) formats.push(format);
-  }
-  return formats.length > 0 ? formats : [DEFAULT_MODEL_FORMAT];
-}
-
-function indexFormatsBySchema(spec, formats) {
-  const formatsBySchema = new Map();
-
-  for (const format of formats) {
-    const schemaNames = collectUsedSchemasForMediaType(spec, {mediaType: format});
-    for (const schemaName of schemaNames) {
-      if (!schemaName) continue;
-      const schemaFormats = formatsBySchema.get(schemaName) ?? new Set();
-      schemaFormats.add(format);
-      formatsBySchema.set(schemaName, schemaFormats);
-    }
-  }
+const HYDRA_SCHEMA = /^Hydra/i;
 
-  return formatsBySchema;
-}
+/** Representations of one resource, in emission order: the JSON-LD one is what the bridge reads. */
+const VARIANT_ORDER = ['jsonld', 'none', 'multipart'];
+const VARIANT_SUFFIX = {jsonld: 'JsonLd', none: 'Json', multipart: 'Multipart'};
 
 function matchesRule(value, rule) {
   if (rule instanceof RegExp) return rule.test(value);
@@ -55,94 +29,81 @@ function isSelected(schemaName, include, exclude) {
   return (include.length === 0 || matchesAny(include)) && !matchesAny(exclude);
 }
 
-function selectCandidates(schemas, formatsBySchema, include, exclude) {
-  const selected = [...formatsBySchema.keys()]
-    .filter((name) => name && !/^Hydra/i.test(name))
-    .sort((left, right) => left.localeCompare(right))
-    .filter((name) => isSelected(name, include, exclude));
-
-  const candidates = include.length > 0 || exclude.length > 0
-    ? expandWithSchemaDependencies(selected, schemas)
-    : new Set(selected);
-
-  return [...candidates]
-    .filter((name) => name && !/^Hydra/i.test(name))
-    .sort((left, right) => left.localeCompare(right));
+/** Hydra schemas are covered by the runtime `Item`/`Collection` types; merge-patch bodies by `Partial<T>`. */
+function isModelSchema(schemaName) {
+  return !HYDRA_SCHEMA.test(schemaName) && !parseOpenApiSchemaName(schemaName).isMergePatch;
 }
 
-function choosePreferredFormats(schemaNames, formats, formatsBySchema) {
-  const formatPriority = new Map(formats.map((format, index) => [format, index]));
-  const preferredFormats = new Map();
-
-  for (const schemaName of schemaNames) {
-    const schemaFormats = [...(formatsBySchema.get(schemaName) ?? [])];
-    const preferred = schemaFormats.sort(
-      (left, right) => (formatPriority.get(left) ?? 999) - (formatPriority.get(right) ?? 999)
-    )[0] ?? formats[0];
-    preferredFormats.set(schemaName, preferred);
-  }
-
-  return {preferredFormats, formatPriority};
+function variantRank(schemaName) {
+  const rank = VARIANT_ORDER.indexOf(parseOpenApiSchemaName(schemaName).baseVariant);
+  return rank < 0 ? VARIANT_ORDER.length : rank;
 }
 
-function desiredTypeName(schemaName) {
+/** Name shared by every representation of a resource (`Book`, `Book.jsonld`, `Book.multipart` → `Book`). */
+export function resourceTypeName(schemaName) {
   const parsed = parseOpenApiSchemaName(schemaName);
-  if (parsed.isMergePatch) return undefined;
-
-  const base = baseTsNameFromBasePath(parsed.basePath);
-  const group = groupTsNameFromGroupPath(parsed.groupPath);
-  return `${base}${group}` || 'Model';
+  return `${baseTsNameFromBasePath(parsed.basePath)}${groupTsNameFromGroupPath(parsed.groupPath)}` || 'Model';
 }
 
-function assignTypeNames(schemaNames, preferredFormats, formatPriority) {
-  const schemasByDesiredName = new Map();
+/** Selects the component schemas of the contract, optionally filtered by `include` / `exclude`. */
+export function selectModelSchemas(spec, options = {}) {
+  const schemas = spec?.components?.schemas ?? {};
+  const include = Array.isArray(options.includeSchemaNames) ? options.includeSchemaNames : [];
+  const exclude = Array.isArray(options.excludeSchemaNames) ? options.excludeSchemaNames : [];
 
-  for (const schemaName of schemaNames) {
-    const desiredName = desiredTypeName(schemaName);
-    if (!desiredName) continue;
+  const selected = Object.keys(schemas)
+    .filter(isModelSchema)
+    .filter((schemaName) => isSelected(schemaName, include, exclude));
+  const schemaNames = include.length > 0 || exclude.length > 0
+    ? [...expandWithSchemaDependencies(selected, schemas)]
+    : selected;
+
+  return {
+    schemas,
+    schemaNames: schemaNames.filter(isModelSchema).sort((left, right) => left.localeCompare(right)),
+  };
+}
 
-    const entries = schemasByDesiredName.get(desiredName) ?? [];
-    entries.push({schemaName, preferredFormat: preferredFormats.get(schemaName)});
-    schemasByDesiredName.set(desiredName, entries);
+/**
+ * Names the models: the representations of one resource that have the same TypeScript shape share one model,
+ * named after the resource. A representation with a different shape gets its variant as suffix.
+ *
+ * @param {string[]} schemaNames
+ * @param {Map<string, string>} signatures shape of each schema, computed with resource names
+ * @returns {{typeNames: Map<string, string>, emitted: string[]}}
+ */
+export function assignTypeNames(schemaNames, signatures) {
+  const representations = new Map();
+  for (const schemaName of schemaNames) {
+    const resourceName = resourceTypeName(schemaName);
+    representations.set(resourceName, [...(representations.get(resourceName) ?? []), schemaName]);
   }
 
   const usedNames = new Set();
   const typeNames = new Map();
-  const sortedGroups = [...schemasByDesiredName.entries()]
-    .sort(([left], [right]) => left.localeCompare(right));
-
-  for (const [desiredName, entries] of sortedGroups) {
-    entries.sort((left, right) => {
-      const byFormat =
-        (formatPriority.get(left.preferredFormat) ?? 999) -
-        (formatPriority.get(right.preferredFormat) ?? 999);
-      return byFormat || left.schemaName.localeCompare(right.schemaName);
-    });
-
-    entries.forEach((entry, index) => {
-      const candidateName = index === 0
-        ? desiredName
-        : `${desiredName}${formatSuffixToken(entry.preferredFormat)}`;
-      typeNames.set(entry.schemaName, sanitizeTypeName(candidateName, usedNames));
-    });
+  const emitted = [];
+  const sortedResources = [...representations.entries()].sort(([left], [right]) => left.localeCompare(right));
+
+  for (const [resourceName, names] of sortedResources) {
+    names.sort((left, right) => variantRank(left) - variantRank(right) || left.localeCompare(right));
+    const typeNameBySignature = new Map();
+
+    for (const schemaName of names) {
+      const signature = signatures.get(schemaName);
+      const sameShape = typeNameBySignature.get(signature);
+      if (sameShape) {
+        typeNames.set(schemaName, sameShape);
+        continue;
+      }
+
+      const variant = parseOpenApiSchemaName(schemaName).baseVariant;
+      const candidate = typeNameBySignature.size === 0 ? resourceName : `${resourceName}${VARIANT_SUFFIX[variant] ?? ''}`;
+      const typeName = sanitizeTypeName(candidate, usedNames);
+      typeNameBySignature.set(signature, typeName);
+      typeNames.set(schemaName, typeName);
+      emitted.push(schemaName);
+    }
   }
 
-  return typeNames;
-}
-
-export function selectModelSchemas(spec, options = {}) {
-  const schemas = spec?.components?.schemas ?? {};
-  const formats = normalizeFormats(options.formats);
-  const include = Array.isArray(options.includeSchemaNames) ? options.includeSchemaNames : [];
-  const exclude = Array.isArray(options.excludeSchemaNames) ? options.excludeSchemaNames : [];
-  const formatsBySchema = indexFormatsBySchema(spec, formats);
-  const schemaNames = selectCandidates(schemas, formatsBySchema, include, exclude);
-  const {preferredFormats, formatPriority} = choosePreferredFormats(
-    schemaNames,
-    formats,
-    formatsBySchema
-  );
-  const typeNames = assignTypeNames(schemaNames, preferredFormats, formatPriority);
-
-  return {schemas, formats, schemaNames, preferredFormats, typeNames};
+  return {typeNames, emitted};
 }

package/src/generators/models/oas-contract.js

@@ -1,30 +1,4 @@
-import {resolveLocalRef, schemaNameFromRef} from './schema-utils.js';
-
-function deref(spec, maybeRef) {
-  if (!maybeRef || typeof maybeRef !== 'object') return maybeRef;
-  if (typeof maybeRef.$ref === 'string') return resolveLocalRef(spec, maybeRef.$ref) || maybeRef;
-  return maybeRef;
-}
-
-export function canonicalizeMediaType(mediaType) {
-  return String(mediaType || '').split(';')[0].trim().toLowerCase();
-}
-
-function getContentSchema(content, wantedLower) {
-  if (!content || typeof content !== 'object') return undefined;
-  for (const [mediaType, definition] of Object.entries(content)) {
-    if (canonicalizeMediaType(mediaType) === wantedLower) return definition?.schema;
-  }
-  return undefined;
-}
-
-function is2xxStatus(code) {
-  const status = String(code || '');
-  if (/^[0-9]{3}$/.test(status)) return status.startsWith('2');
-  return /^2xx$/i.test(status);
-}
-
-const HTTP_METHODS = new Set(['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace']);
+import {schemaNameFromRef} from './schema-utils.js';
 
 /**
  * Collects only component schema refs (`#/components/schemas/*`) found in a JSON schema.
@@ -57,74 +31,6 @@ function collectComponentSchemaRefs(schema, out) {
   walk(schema);
 }
 
-function listSchemaRoots(spec, {mediaType} = {}) {
-  const wantedLower = canonicalizeMediaType(mediaType);
-  const roots = [];
-  const visited = new Set();
-
-  function addParameter(parameterOrRef) {
-    const parameter = deref(spec, parameterOrRef);
-    if (!parameter || typeof parameter !== 'object') return;
-    if (parameter.schema) roots.push(parameter.schema);
-    const contentSchema = getContentSchema(parameter.content, wantedLower);
-    if (contentSchema) roots.push(contentSchema);
-  }
-
-  function addHeaders(headers) {
-    for (const header of Object.values(headers ?? {})) addParameter(header);
-  }
-
-  function visitOperation(method, operationOrRef) {
-    const operation = deref(spec, operationOrRef);
-    if (!operation || typeof operation !== 'object') return;
-    if (visited.has(operation)) return;
-    visited.add(operation);
-
-    for (const parameter of operation.parameters ?? []) addParameter(parameter);
-
-    if (method !== 'patch') {
-      const requestBody = deref(spec, operation.requestBody);
-      const requestSchema = getContentSchema(requestBody?.content, wantedLower);
-      if (requestSchema) roots.push(requestSchema);
-    }
-
-    for (const [code, responseOrRef] of Object.entries(operation.responses ?? {})) {
-      if (!is2xxStatus(code) && String(code).toLowerCase() !== 'default') continue;
-      const response = deref(spec, responseOrRef);
-      const responseSchema = getContentSchema(response?.content, wantedLower);
-      if (responseSchema) roots.push(responseSchema);
-      addHeaders(response?.headers);
-    }
-
-    for (const callbackOrRef of Object.values(operation.callbacks ?? {})) {
-      const callback = deref(spec, callbackOrRef);
-      for (const pathItem of Object.values(callback ?? {})) visitPathItem(pathItem);
-    }
-  }
-
-  function visitPathItem(pathItemOrRef) {
-    const pathItem = deref(spec, pathItemOrRef);
-    if (!pathItem || typeof pathItem !== 'object') return;
-    if (visited.has(pathItem)) return;
-    visited.add(pathItem);
-
-    for (const parameter of pathItem.parameters ?? []) addParameter(parameter);
-    for (const [method, operation] of Object.entries(pathItem)) {
-      const normalizedMethod = method.toLowerCase();
-      if (HTTP_METHODS.has(normalizedMethod)) visitOperation(normalizedMethod, operation);
-    }
-  }
-
-  function visitPaths(paths) {
-    for (const pathItem of Object.values(paths ?? {})) visitPathItem(pathItem);
-  }
-
-  visitPaths(spec?.paths);
-  visitPaths(spec?.webhooks);
-
-  return roots;
-}
-
 /**
  * Returns the transitive closure of schema dependencies (following component-schema $ref).
  * @param {Iterable<string>} start
@@ -155,16 +61,3 @@ export function expandWithSchemaDependencies(start, schemas) {
 
   return out;
 }
-
-/**
- * Collects all component schemas used by endpoints for one media type.
- * @param {any} spec
- * @param {{ mediaType: string }} cfg
- */
-export function collectUsedSchemasForMediaType(spec, cfg) {
-  const schemas = spec?.components?.schemas || {};
-  const roots = listSchemaRoots(spec, cfg);
-  const initialRefs = new Set();
-  for (const root of roots) collectComponentSchemaRefs(root, initialRefs);
-  return expandWithSchemaDependencies(initialRefs, schemas);
-}

package/src/generators/models/oas-schema-name.js

@@ -1,4 +1,3 @@
-import { canonicalizeMediaType } from './oas-contract.js';
 import {pascalCase} from './utils.js';
 
 export function parseOpenApiSchemaName(originalName) {
@@ -26,17 +25,7 @@ export function parseOpenApiSchemaName(originalName) {
     groupRaw = groupRaw.replace(/\.jsonmergepatch$/i, '');
   }
 
-  const basePath = baseRaw;
-  const groupPath = groupRaw;
-
-  return {
-    originalName: raw,
-    basePath,
-    groupPath,
-    baseVariant,
-    isMergePatch,
-    key: `${basePath.toLowerCase()}|${groupPath.toLowerCase()}`,
-  };
+  return {basePath: baseRaw, groupPath: groupRaw, baseVariant, isMergePatch};
 }
 
 export function baseTsNameFromBasePath(basePath) {
@@ -53,10 +42,3 @@ export function groupTsNameFromGroupPath(groupPath) {
   const tokens = String(groupPath || '').split(/[._:]+/g).filter(Boolean);
   return pascalCase(tokens);
 }
-
-export function formatSuffixToken(mediaType) {
-  const canon = canonicalizeMediaType(mediaType);
-  const tokens = canon.split(/[\/+.-]+/g).filter(Boolean);
-  const trimmed = tokens[0] === 'application' ? tokens.slice(1) : tokens;
-  return pascalCase(trimmed.length ? trimmed : tokens) || 'Fmt';
-}

package/src/generators/models/openapi-to-models.js

@@ -1,14 +1,12 @@
-import {canonicalizeMediaType} from './oas-contract.js';
 import {collectInterfaceTypeNames, resolveInterfaceSchema} from './interface-schema.js';
-import {DEFAULT_MODEL_FORMAT, selectModelSchemas} from './model-selection.js';
-import {isObject} from './schema-utils.js';
+import {assignTypeNames, resourceTypeName, selectModelSchemas} from './model-selection.js';
+import {parseOpenApiSchemaName} from './oas-schema-name.js';
+import {isObject, schemaNameFromRef} from './schema-utils.js';
 import {createTypeResolver} from './type-resolver.js';
 import {quoteKeyIfNeeded} from './utils.js';
 
 /**
  * @typedef {{
- *   requiredMode?: 'all'|'spec',
- *   formats?: string[],
  *   includeSchemaNames?: Array<RegExp|string|((name: string) => boolean)>,
  *   excludeSchemaNames?: Array<RegExp|string|((name: string) => boolean)>,
  * }} BuildOptions
@@ -28,12 +26,12 @@ import {quoteKeyIfNeeded} from './utils.js';
  * }} ModelDefinition
  */
 
-function normalizeRequiredMode(value) {
-  return String(value ?? '').trim().toLowerCase() === 'spec' ? 'spec' : 'all';
-}
+const JSON_LD_KEYWORDS = new Set(['@id', '@type', '@context']);
+const HYDRA_SCHEMA = /^Hydra/i;
 
-function createModelBuilder({spec, schemas, typeNames, interfaceTypeNames, requiredMode}) {
+function createModelBuilder({spec, schemas, schemaNames, typeNames}) {
   const knownTypeNames = new Set(typeNames.values());
+  const interfaceTypeNames = collectInterfaceTypeNames(schemas, schemaNames, typeNames);
 
   function importsFor(dependencies, currentTypeName) {
     return [...dependencies]
@@ -42,7 +40,7 @@ function createModelBuilder({spec, schemas, typeNames, interfaceTypeNames, requi
   }
 
   function resolverFor(dependencies) {
-    return createTypeResolver({dependencies, typeNames, requiredMode, spec});
+    return createTypeResolver({dependencies, typeNames, spec});
   }
 
   function buildAlias(raw, typeName) {
@@ -58,21 +56,28 @@ function createModelBuilder({spec, schemas, typeNames, interfaceTypeNames, requi
     };
   }
 
-  function buildInterface(schema, typeName, extendsTypes, preferredFormat) {
-    const isJsonLd = canonicalizeMediaType(preferredFormat) === DEFAULT_MODEL_FORMAT;
+  /** Whether the Hydra base schema of a representation requires `@id` and `@type`, like the runtime `Item`. */
+  function isHydraItem(raw) {
+    return (raw?.allOf ?? []).some((part) => {
+      const baseName = part?.$ref ? schemaNameFromRef(part.$ref) : undefined;
+      const required = baseName && HYDRA_SCHEMA.test(baseName) ? schemas[baseName]?.required ?? [] : [];
+      return required.includes('@id') && required.includes('@type');
+    });
+  }
+
+  /** A JSON-LD item extends the runtime `Item`, which carries `@id`, `@type` and `@context`. */
+  function buildInterface(schema, typeName, extendsTypes, isJsonLd, extendsItem) {
     const requiredProperties = new Set(schema.required ?? []);
     const dependencies = new Set(extendsTypes);
     const resolver = resolverFor(dependencies);
 
     const props = Object.entries(schema.properties ?? {})
-      .filter(([propertyName]) => !isJsonLd || !['@id', '@type', '@context'].includes(propertyName))
+      .filter(([propertyName]) => !isJsonLd || !JSON_LD_KEYWORDS.has(propertyName))
       .map(([propertyName, propertySchema]) => ({
         name: propertyName,
         tsKey: quoteKeyIfNeeded(propertyName),
-        type: requiredMode === 'spec'
-          ? resolver.typeOf(propertySchema)
-          : resolver.nullableTypeOf(propertySchema),
-        optional: requiredMode === 'spec' ? !requiredProperties.has(propertyName) : true,
+        type: resolver.typeOf(propertySchema),
+        optional: !requiredProperties.has(propertyName),
       }));
 
     return {
@@ -80,11 +85,11 @@ function createModelBuilder({spec, schemas, typeNames, interfaceTypeNames, requi
       props,
       imports: importsFor(dependencies, typeName),
       extendsTypes,
-      extendsItem: isJsonLd,
+      extendsItem,
     };
   }
 
-  return function buildModel(schemaName, preferredFormat) {
+  return function buildModel(schemaName) {
     const raw = schemas[schemaName];
     const typeName = typeNames.get(schemaName);
     if (!typeName || raw === undefined) return undefined;
@@ -100,37 +105,41 @@ function createModelBuilder({spec, schemas, typeNames, interfaceTypeNames, requi
       return buildAlias(raw, typeName);
     }
 
-    return buildInterface(schema, typeName, extendsTypes, preferredFormat);
+    const isJsonLd = parseOpenApiSchemaName(schemaName).baseVariant === 'jsonld';
+    return buildInterface(schema, typeName, extendsTypes, isJsonLd, isJsonLd && isHydraItem(raw));
   };
 }
 
+/** TypeScript shape of a model, independent of its name and of the `Item` base. */
+function signatureOf(model) {
+  if (!model) return '';
+  return JSON.stringify([
+    model.isAlias ? model.type : null,
+    model.extendsTypes,
+    model.props.map(({name, type, optional}) => [name, type, optional]),
+  ]);
+}
+
 /**
- * Builds TypeScript model definitions from OpenAPI `components.schemas`.
+ * Builds TypeScript model definitions from the OpenAPI `components.schemas`.
+ *
+ * API Platform describes one resource several times (`Book.jsonld`, `Book`, `Book.multipart`). Representations
+ * with the same shape produce a single model, built from the JSON-LD one when present.
+ *
  * @param {any} spec
  * @param {BuildOptions} [options]
  * @returns {{models: ModelDefinition[]}}
  */
 export function buildModelsFromOpenAPI(spec, options = {}) {
-  const requiredMode = normalizeRequiredMode(options.requiredMode);
-  const {schemas, formats, schemaNames, preferredFormats, typeNames} = selectModelSchemas(
-    spec,
-    options
-  );
-  const interfaceTypeNames = collectInterfaceTypeNames(schemas, schemaNames, typeNames);
-  const buildModel = createModelBuilder({
-    spec,
-    schemas,
-    typeNames,
-    interfaceTypeNames,
-    requiredMode,
-  });
-
-  const models = [];
-  for (const schemaName of schemaNames) {
-    const preferredFormat = preferredFormats.get(schemaName) ?? formats[0];
-    const model = buildModel(schemaName, preferredFormat);
-    if (model) models.push(model);
-  }
+  const {schemas, schemaNames} = selectModelSchemas(spec, options);
+  const builderFor = (typeNames) => createModelBuilder({spec, schemas, schemaNames, typeNames});
+
+  // Representations of a resource are compared with the resource name, so references do not tell them apart.
+  const buildWithResourceNames = builderFor(new Map(schemaNames.map((name) => [name, resourceTypeName(name)])));
+  const signatures = new Map(schemaNames.map((name) => [name, signatureOf(buildWithResourceNames(name))]));
+
+  const {typeNames, emitted} = assignTypeNames(schemaNames, signatures);
+  const buildModel = builderFor(typeNames);
 
-  return {models};
+  return {models: emitted.map(buildModel).filter(Boolean)};
 }