openapi-typesafe 1.0.0-rc.3 → 1.0.0-rc.5

package/src/application/transform/ref-pointer/original-index.ts

@@ -1,11 +1,15 @@
 import type { RefResolver, SchemaOptions } from "../schema/schema-context.js";
-import { followRefs, generatedMember, isJsonObject } from "./generated-shape.js";
+import { generatedMember } from "./generated-shape.js";
+import { childLocation, followLocated, isJsonObject } from "./located-node.js";
 import {
+  type ContentForm,
+  headerParameterContentForm,
+  isExcludedOperation,
   isOptionalHeader,
   isOptionalRequestBody,
   isParameterList,
   isTypedAsSchema,
-  leadingNode,
+  leadingLocated,
   leadingSegmentsOf,
   type RefPointer,
   startsInSchema,
@@ -22,6 +26,8 @@ type Step = "fails" | "compiles" | "continue";
 
 interface OriginalWalk {
   readonly node: unknown;
+  /** The node's JSON Pointer (`LocatedNode`). */
+  readonly location: string | undefined;
   readonly isSchema: boolean;
 }
 
@@ -35,7 +41,7 @@ function schemaStep(walk: OriginalWalk, segment: string, isLast: boolean, input:
   if (segment === "properties") {
     return { step: "continue" as Step, walk };
   }
-  const member = generatedMember(walk.node, segment, input.options, input.refs);
+  const member = generatedMember(walk, segment, input.options, input.refs);
   if (member.kind === "missing") {
     return { step: "fails" as Step, walk };
   }
@@ -43,49 +49,126 @@ function schemaStep(walk: OriginalWalk, segment: string, isLast: boolean, input:
     return { step: "compiles" as Step, walk };
   }
   const isAbsentValue = member.kind === "index" && member.node === undefined;
-  const isUnsafe = member.kind === "property" ? member.isOptional : isAbsentValue;
+  const isUnsafe =
+    member.kind === "property" ? member.isOptional || member.isMarked : isAbsentValue;
   return {
     step: (isUnsafe && !isLast ? "fails" : "continue") as Step,
-    walk: { ...walk, node: member.node },
+    walk: { ...walk, node: member.node, location: member.location },
   };
 }
 
 function containerStep(walk: OriginalWalk, index: number, input: WalkInput) {
   const segment = input.pointer.segments[index] as string;
   const isLast = index === input.pointer.segments.length - 1;
+  if (isExcludedOperation(input.pointer, index, walk.node, input)) {
+    return { step: "fails" as Step, walk };
+  }
   const isOptional =
     (segment === "requestBody" && isOptionalRequestBody(walk.node, input.refs)) ||
     isOptionalHeader(input.pointer, index, walk.node);
   if (isOptional && !isLast) {
     return { step: "fails" as Step, walk };
   }
-  const child = isJsonObject(walk.node) ? followRefs(walk.node[segment], input.refs) : undefined;
+  const child = followLocated(
+    {
+      node: isJsonObject(walk.node) ? walk.node[segment] : undefined,
+      location: childLocation(walk.location, segment),
+    },
+    input.refs,
+  );
   return {
-    step: (child === undefined ? "compiles" : "continue") as Step,
-    walk: { ...walk, node: child },
+    step: (child.node === undefined ? "compiles" : "continue") as Step,
+    walk: { ...walk, ...child },
   };
 }
 
+/** The schema of the first media type of a `content` map, `$ref`s followed. */
+function firstMediaTypeSchema(walk: OriginalWalk, refs: RefResolver): OriginalWalk | null {
+  const content = isJsonObject(walk.node) ? walk.node.content : undefined;
+  if (!isJsonObject(content)) {
+    return null;
+  }
+  const [mediaType] = Object.keys(content);
+  if (mediaType === undefined) {
+    return null;
+  }
+  const location = childLocation(childLocation(walk.location, "content"), mediaType);
+  const entry = followLocated({ node: content[mediaType], location }, refs);
+  return ownSchema({ ...entry, isSchema: false }, refs);
+}
+
+/** The schema a header or parameter is typed by, `$ref`s followed. */
+function ownSchema(walk: OriginalWalk, refs: RefResolver): OriginalWalk {
+  const schema = isJsonObject(walk.node) ? walk.node.schema : undefined;
+  const location = childLocation(walk.location, "schema");
+  return { ...followLocated({ node: schema, location }, refs), isSchema: true };
+}
+
+/** The schema whose type a header or parameter is, when not its media type members. */
+function contentSchema(
+  walk: OriginalWalk,
+  form: Exclude<ContentForm, "media-type-members">,
+  refs: RefResolver,
+): OriginalWalk | null {
+  switch (form) {
+    case "first-media-type":
+      return firstMediaTypeSchema(walk, refs);
+    case "schema":
+      return ownSchema(walk, refs);
+    case "string":
+      return null;
+  }
+}
+
+/**
+ * The original indexes the `content` of a header or parameter by name. The media type members
+ * have no `content` unless a media type is named so, and `string` and `unknown` (no media type)
+ * have none; the schema of the first media type, or the `schema` next to `content`, is walked on.
+ */
+function contentStep(walk: OriginalWalk, form: ContentForm, isLast: boolean, input: WalkInput) {
+  const content = isJsonObject(walk.node) ? walk.node.content : undefined;
+  if (form === "media-type-members") {
+    const hasMember = isJsonObject(content) && Object.hasOwn(content, "content");
+    return { step: (hasMember ? "compiles" : "fails") as Step, walk };
+  }
+  const schema = contentSchema(walk, form, input.refs);
+  return schema === null
+    ? { step: "fails" as Step, walk }
+    : schemaStep(schema, "content", isLast, input);
+}
+
+/**
+ * A step outside a schema: a header's or parameter's `content`, a schema's container, or another.
+ */
+function documentStep(walk: OriginalWalk, index: number, input: WalkInput) {
+  const segment = input.pointer.segments[index] as string;
+  const isLast = index === input.pointer.segments.length - 1;
+  const form = headerParameterContentForm(input.pointer, index, walk.node, input.options);
+  if (form !== null) {
+    return contentStep(walk, form, isLast, input);
+  }
+  if (isTypedAsSchema(input.pointer, index) && isJsonObject(walk.node)) {
+    // The container's type is its schema's type: the segment indexes that type.
+    return schemaStep(ownSchema(walk, input.refs), segment, isLast, input);
+  }
+  return containerStep(walk, index, input);
+}
+
 /** True when the original type of the `$ref` does not compile for sure. */
 export function originalIndexFails(input: WalkInput): boolean {
   const { segments } = input.pointer;
   let walk: OriginalWalk = {
-    node: leadingNode(input.pointer, input.refs),
+    ...leadingLocated(input.pointer, input.refs),
     isSchema: startsInSchema(input.pointer),
   };
   for (let index = leadingSegmentsOf(input.pointer); index < segments.length; index++) {
-    const segment = segments[index] as string;
-    const isLast = index === segments.length - 1;
     if (!walk.isSchema && isParameterList(input.pointer, index)) {
       return true;
     }
-    if (!walk.isSchema && isTypedAsSchema(input.pointer, index) && isJsonObject(walk.node)) {
-      // The container's type is its schema's type: the segment indexes that type.
-      walk = { node: followRefs(walk.node.schema, input.refs), isSchema: true };
-    }
+    const isLast = index === segments.length - 1;
     const result = walk.isSchema
-      ? schemaStep(walk, segment, isLast, input)
-      : containerStep(walk, index, input);
+      ? schemaStep(walk, segments[index] as string, isLast, input)
+      : documentStep(walk, index, input);
     if (result.step !== "continue") {
       return result.step === "fails";
     }

package/src/application/transform/ref-pointer/pointer-type.ts

@@ -4,8 +4,8 @@ import { FIX } from "../../../domain/output-fixes.js";
 import { InvalidRefError, refType } from "../ref-type.js";
 import type { SchemaRequest } from "../schema/schema-rule.js";
 import { generatedLocationOf } from "./generated-location.js";
-import { isJsonObject } from "./generated-shape.js";
 import { hasInlineCycle } from "./inline-cycles.js";
+import { isJsonObject } from "./located-node.js";
 import { originalIndexFails } from "./original-index.js";
 import { leadingSegmentsOf, pointerNode, type RefPointer, refPointerOf } from "./pointer-walk.js";
 import { typedWalk } from "./typed-walk.js";

package/src/application/transform/ref-pointer/pointer-walk.ts

@@ -1,6 +1,15 @@
-import { parseRefPointer } from "../../../domain/openapi/json-pointer.js";
-import type { RefResolver } from "../schema/schema-context.js";
-import { followRefs, isJsonObject } from "./generated-shape.js";
+import { placeOf } from "../../../domain/openapi/document-places.js";
+import { parseRefPointer, ROOT_POINTER } from "../../../domain/openapi/json-pointer.js";
+import { QUERYSTRING_LOCATION } from "../../../domain/openapi/parameter-object.js";
+import { FIX } from "../../../domain/output-fixes.js";
+import type { RefResolver, SchemaOptions } from "../schema/schema-context.js";
+import {
+  childLocation,
+  followLocated,
+  followRefs,
+  isJsonObject,
+  type LocatedNode,
+} from "./located-node.js";
 
 /** The parts of a `$ref` pointer that both the original and the new types walk. */
 
@@ -27,13 +36,18 @@ export function refPointerOf(ref: string): RefPointer | null {
   return rootSegment === undefined ? null : { rootSegment, segments };
 }
 
-/** The document node at the end of the leading segments, `$ref`s followed. */
-export function leadingNode(pointer: RefPointer, refs: RefResolver): unknown {
-  let node = refs.resolve(`#/${pointer.rootSegment}`);
+/** The document node at the end of the leading segments, `$ref`s followed, with its location. */
+export function leadingLocated(pointer: RefPointer, refs: RefResolver): LocatedNode {
+  let located: LocatedNode = {
+    node: refs.resolve(`#/${pointer.rootSegment}`),
+    location: childLocation(ROOT_POINTER, pointer.rootSegment),
+  };
   for (const segment of pointer.segments.slice(0, leadingSegmentsOf(pointer))) {
-    node = isJsonObject(node) ? followRefs(node[segment], refs) : undefined;
+    const { node, location } = located;
+    const child = isJsonObject(node) ? node[segment] : undefined;
+    located = followLocated({ node: child, location: childLocation(location, segment) }, refs);
   }
-  return node;
+  return located;
 }
 
 /** The node at the whole pointer, without following a `$ref` at its end. */
@@ -62,6 +76,47 @@ export function isTypedAsSchema(pointer: RefPointer, index: number): boolean {
   return owner === "content" || owner === "headers" || isComponentParameter;
 }
 
+/**
+ * How the generated type of a header or component parameter holds its `content` (header.ts,
+ * parameter.ts): one member per media type, the type of the first media type, `string` (a
+ * parameter without the `parameter-header-content` fix), or not at all (a `schema` wins).
+ */
+export type ContentForm = "media-type-members" | "first-media-type" | "string" | "schema";
+
+/**
+ * The form of the `content` at `index` when it belongs to a header or a component parameter; null
+ * for any other segment. An `in: querystring` parameter is typed by its `content` even next to a
+ * `schema`.
+ */
+export function headerParameterContentForm(
+  pointer: RefPointer,
+  index: number,
+  owner: unknown,
+  options: SchemaOptions,
+): ContentForm | null {
+  const isHeader = pointer.segments[index - 2] === "headers";
+  const isComponentParameter =
+    pointer.rootSegment === "components" && index === 2 && pointer.segments[0] === "parameters";
+  const isOwnContent = pointer.segments[index] === "content" && (isHeader || isComponentParameter);
+  if (!isOwnContent || !isJsonObject(owner)) {
+    return null;
+  }
+  const isFixed = options.fixes.has(FIX.PARAMETER_HEADER_CONTENT);
+  if (isHeader) {
+    if (owner.schema) {
+      return "schema";
+    }
+    return isFixed ? "first-media-type" : "media-type-members";
+  }
+  if (owner.in === QUERYSTRING_LOCATION) {
+    return "first-media-type";
+  }
+  if (owner.schema !== undefined) {
+    return "schema";
+  }
+  return isFixed ? "first-media-type" : "string";
+}
+
 /**
  * Whether the segment at `index` is an operation's or path item's `parameters` list, indexed by
  * position next. The generated type groups parameters by `in` (`query`, `path`), so it has no
@@ -86,6 +141,25 @@ export function isOptionalHeader(pointer: RefPointer, index: number, headers: un
   return isJsonObject(header) && header.$ref === undefined && header.required !== true;
 }
 
+/**
+ * Whether the segment at `index` names an operation that `--exclude-deprecated` leaves out: the
+ * path item types it `never`, which has no member to index (`isIncludedOperation`).
+ */
+export function isExcludedOperation(
+  pointer: RefPointer,
+  index: number,
+  pathItem: unknown,
+  input: { readonly options: SchemaOptions; readonly refs: RefResolver },
+): boolean {
+  const segments = [pointer.rootSegment, ...pointer.segments.slice(0, index + 1)];
+  if (!input.options.excludeDeprecated || placeOf(segments) !== "operation") {
+    return false;
+  }
+  const segment = pointer.segments[index] as string;
+  const operation = isJsonObject(pathItem) ? followRefs(pathItem[segment], input.refs) : undefined;
+  return isJsonObject(operation) && Boolean(operation.deprecated);
+}
+
 /** A `requestBody` the operation does not mark `required` is an optional member. */
 export function isOptionalRequestBody(container: unknown, refs: RefResolver): boolean {
   if (!isJsonObject(container) || container.requestBody === undefined) {

package/src/application/transform/ref-pointer/property-shape.ts

@@ -0,0 +1,97 @@
+import type { Schema } from "../../../domain/openapi/schema-object.js";
+import { propertyAccessFlags } from "../schema/access-flags.js";
+import { isInputLocation } from "../schema/input-location.js";
+import type { RefResolver, SchemaOptions } from "../schema/schema-context.js";
+import {
+  followLocated,
+  followRefs,
+  isJsonObject,
+  type JsonObject,
+  type LocatedNode,
+} from "./located-node.js";
+
+/**
+ * What the generated type of an object schema makes of one of its properties: optional, left
+ * out, wrapped in a read or write marker, or a value that may be `undefined` or `null`.
+ */
+
+/** `nullable: true` or a `type` list with `null`: the generated type includes `null`. */
+export function isNullableSchema(node: unknown): boolean {
+  if (!isJsonObject(node)) {
+    return false;
+  }
+  return node.nullable === true || (Array.isArray(node.type) && node.type.includes("null"));
+}
+
+/**
+ * Whether the generated type has the property as optional, as `objectType` decides: a `default`
+ * makes a property required except in an input location, where the client may leave it out.
+ */
+export function isOptionalProperty(
+  owner: LocatedNode & { node: JsonObject },
+  key: string,
+  options: SchemaOptions,
+): boolean {
+  const { node } = owner;
+  const required = Array.isArray(node.required) ? node.required : undefined;
+  const property = (node.properties as JsonObject)[key];
+  const hasDefault = isJsonObject(property) && property.default !== undefined;
+  const isDefaultRequired =
+    hasDefault && options.defaultNonNullable && !isInputLocation(owner.location, options.fixes);
+  const isRequired =
+    required?.includes(key) === true ||
+    (required === undefined && options.propertiesRequiredByDefault) ||
+    isDefaultRequired;
+  return !isRequired;
+}
+
+/**
+ * Whether `--exclude-deprecated` leaves the property out: its object, or the one its `$ref`
+ * names, is deprecated (`objectType`). The key is then not in the generated type at all.
+ */
+export function isExcludedProperty(
+  property: unknown,
+  options: SchemaOptions,
+  refs: RefResolver,
+): boolean {
+  const resolved = followRefs(property, refs);
+  return options.excludeDeprecated && isJsonObject(resolved) && Boolean(resolved.deprecated);
+}
+
+/**
+ * Whether `--read-write-markers` wraps the type of a property or `$defs` member: one that is only
+ * `readOnly` or only `writeOnly` is `$Read<T>` or `$Write<T>` (object-type.ts).
+ */
+export function isMarkedProperty(value: unknown, options: SchemaOptions, refs: RefResolver) {
+  if (!options.readWriteMarkers || !isJsonObject(value)) {
+    return false;
+  }
+  const flags = propertyAccessFlags(value as Schema, { options, refs });
+  return flags.isReadOnly !== flags.isWriteOnly;
+}
+
+/** Whether a value is there: `present`, `absent` (may be `undefined` or `null`) or `unknown`. */
+export type Presence = "present" | "absent" | "unknown";
+
+/** The presence of a value of `schema` itself: `absent` when its type includes `null`. */
+export function schemaPresence(schema: unknown, refs: RefResolver): Presence {
+  return isNullableSchema(followRefs(schema, refs)) ? "absent" : "present";
+}
+
+/** The presence of property `key` of `schema`: optional or nullable is `absent`. */
+export function propertyPresence(
+  schema: LocatedNode,
+  key: string,
+  options: SchemaOptions,
+  refs: RefResolver,
+): Presence {
+  const owner = followLocated(schema, refs);
+  const { node } = owner;
+  const properties = isJsonObject(node) && isJsonObject(node.properties) ? node.properties : {};
+  if (!isJsonObject(node) || !Object.hasOwn(properties, key)) {
+    return "unknown";
+  }
+  return isOptionalProperty({ ...owner, node }, key, options)
+    ? "absent"
+    : schemaPresence(properties[key], refs);
+}

package/src/application/transform/ref-pointer/typed-walk.ts

@@ -2,25 +2,34 @@ import { irIndexedAccess, irKeyword, irReference } from "../../../domain/ir/cons
 import type { IrKeyword, IrType } from "../../../domain/ir/nodes.js";
 import { indexBy, indexKeyword, rootType } from "../ref-type.js";
 import type { RefResolver, SchemaOptions } from "../schema/schema-context.js";
+import { isArrayShape, isObjectShape } from "./generated-shape.js";
 import {
+  childLocation,
+  followLocated,
   followRefs,
-  isArrayShape,
   isJsonObject,
-  isObjectShape,
-  type Presence,
-  propertyPresence,
-  schemaPresence,
-} from "./generated-shape.js";
+  type LocatedNode,
+} from "./located-node.js";
 import {
+  type ContentForm,
+  headerParameterContentForm,
+  isExcludedOperation,
   isOptionalHeader,
   isOptionalRequestBody,
   isParameterList,
   isTypedAsSchema,
-  leadingNode,
+  leadingLocated,
   leadingSegmentsOf,
   type RefPointer,
   startsInSchema,
 } from "./pointer-walk.js";
+import {
+  isExcludedProperty,
+  isMarkedProperty,
+  type Presence,
+  propertyPresence,
+  schemaPresence,
+} from "./property-shape.js";
 
 /**
  * The type of a `$ref` pointer as the generated types have it: the `schema` of a media type,
@@ -36,9 +45,18 @@ export interface TypedWalk {
   readonly type: IrType;
   /** The document node the type stands for (not followed through a `$ref`). */
   readonly node: unknown;
+  /** The node's JSON Pointer, where the generator writes its type (`LocatedNode`). */
+  readonly location: string | undefined;
   readonly isSchema: boolean;
   /** The segment is a property or `$defs` name, not a keyword. */
   readonly isName: boolean;
+  /** The location of the map of names (`properties` or `$defs`) when `isName`. */
+  readonly namesLocation?: string | undefined;
+  /**
+   * The node is the `content` of a header or parameter typed as its first media type, so the
+   * next segment must name that media type and adds no member.
+   */
+  readonly isFirstMediaType?: boolean;
   readonly presence: Presence;
 }
 
@@ -58,19 +76,32 @@ function present(walk: TypedWalk): IrType {
 }
 
 function indexEntries(walk: TypedWalk, key: IrKeyword, keyword: string, refs: RefResolver) {
-  const owner = followRefs(walk.node, refs);
-  const child = isJsonObject(owner) ? owner[keyword] : undefined;
+  const owner = followLocated(walk, refs);
+  const child = isJsonObject(owner.node) ? owner.node[keyword] : undefined;
   return {
     ...walk,
     type: irIndexedAccess(present(walk), irKeyword(key)),
     node: child,
+    location: childLocation(owner.location, keyword),
     presence: schemaPresence(child, refs),
   };
 }
 
+/**
+ * A property `--exclude-deprecated` left out has no member to index, and the `$Read<T>` or
+ * `$Write<T>` of a marked property has no member but the marker's: such a pointer is typed in
+ * place.
+ */
 function nameStep(walk: TypedWalk, name: string, isLast: boolean, input: TypedWalkInput) {
-  const owner = followRefs(walk.node, input.refs);
-  const properties = isJsonObject(owner) && isJsonObject(owner.properties) ? owner.properties : {};
+  const owner = followLocated(walk, input.refs);
+  const { node } = owner;
+  const properties = isJsonObject(node) && isJsonObject(node.properties) ? node.properties : {};
+  const value = properties[name];
+  const { options, refs } = input;
+  const isMarkedOnTheWay = !isLast && isMarkedProperty(value, options, refs);
+  if (isExcludedProperty(value, options, refs) || isMarkedOnTheWay) {
+    return null;
+  }
   const type =
     walk.presence === "present"
       ? indexKeyword(walk.type, name, isLast)
@@ -78,19 +109,25 @@ function nameStep(walk: TypedWalk, name: string, isLast: boolean, input: TypedWa
   return {
     ...walk,
     type,
-    node: properties[name],
+    node: value,
+    location: childLocation(walk.namesLocation, name),
     isName: false,
-    presence: propertyPresence(walk.node, name, input.options, input.refs),
+    presence: propertyPresence(walk, name, input.options, input.refs),
   };
 }
 
 /** `$defs` is optional (`NonNullable` when more follows); its members are present. */
-function defsStep(walk: TypedWalk, owner: unknown, isLast: boolean): TypedWalk {
-  const defs = isJsonObject(owner) && isJsonObject(owner[DEFS_KEYWORD]) ? owner[DEFS_KEYWORD] : {};
+function defsStep(walk: TypedWalk, owner: LocatedNode, isLast: boolean): TypedWalk {
+  const { node } = owner;
+  const defs = isJsonObject(node) && isJsonObject(node[DEFS_KEYWORD]) ? node[DEFS_KEYWORD] : {};
+  const namesLocation = childLocation(owner.location, DEFS_KEYWORD);
   return {
     ...walk,
     type: indexKeyword(present(walk), DEFS_KEYWORD, isLast),
+    // A node of its own, not in the document: its properties are the definitions.
     node: { properties: defs, required: Object.keys(defs) },
+    location: namesLocation,
+    namesLocation,
     isName: true,
     presence: "present",
   };
@@ -115,13 +152,13 @@ function hasKeywordMember(owner: unknown, segment: string): boolean {
 }
 
 function keywordStep(walk: TypedWalk, segment: string, isLast: boolean, input: TypedWalkInput) {
-  const owner = followRefs(walk.node, input.refs);
-  if (!hasKeywordMember(owner, segment)) {
+  const owner = followLocated(walk, input.refs);
+  if (!hasKeywordMember(owner.node, segment)) {
     return null;
   }
   switch (segment) {
     case "properties":
-      return { ...walk, isName: true };
+      return { ...walk, isName: true, namesLocation: childLocation(owner.location, segment) };
     case "items":
       return indexEntries(walk, "number", "items", input.refs);
     case "additionalProperties":
@@ -143,10 +180,65 @@ function containerStep(walk: TypedWalk, index: number, input: TypedWalkInput): T
     ...walk,
     type: indexBy(present(walk), segment),
     node: isJsonObject(owner) ? owner[segment] : undefined,
+    location: childLocation(followLocated(walk, input.refs).location, segment),
     presence: isOptional ? "absent" : "present",
   };
 }
 
+/**
+ * The `content` of a header or parameter: no member of its own, since the type holds its media
+ * types (or the first one's type). Untyped where the type is `string` or a `schema`'s, and as the
+ * last segment of the first media type form, whose type is not the map's.
+ */
+function contentStep(walk: TypedWalk, form: ContentForm, isLast: boolean, refs: RefResolver) {
+  const isMapTyped = form === "media-type-members" || (form === "first-media-type" && !isLast);
+  if (!isMapTyped) {
+    return null;
+  }
+  const owner = followLocated(walk, refs);
+  return {
+    ...walk,
+    node: isJsonObject(owner.node) ? owner.node.content : undefined,
+    location: childLocation(owner.location, "content"),
+    isFirstMediaType: form === "first-media-type",
+  };
+}
+
+/** The first media type of such a `content` is the type itself; another one has no type. */
+function firstMediaTypeStep(walk: TypedWalk, segment: string): TypedWalk | null {
+  const content = isJsonObject(walk.node) ? walk.node : {};
+  if (Object.keys(content)[0] !== segment) {
+    return null;
+  }
+  const location = childLocation(walk.location, segment);
+  return { ...walk, node: content[segment], location, isFirstMediaType: false };
+}
+
+function schemaStep(walk: TypedWalk, refs: RefResolver): TypedWalk {
+  const owner = followLocated(walk, refs);
+  const schema = isJsonObject(owner.node) ? owner.node.schema : undefined;
+  const location = childLocation(owner.location, "schema");
+  // The container's type is its schema's type: an optional header stays optional.
+  const presence = walk.presence === "absent" ? "absent" : schemaPresence(schema, refs);
+  return { ...walk, node: schema, location, isSchema: true, presence };
+}
+
+function documentStep(walk: TypedWalk, index: number, input: TypedWalkInput): TypedWalk | null {
+  const owner = followRefs(walk.node, input.refs);
+  const form = headerParameterContentForm(input.pointer, index, owner, input.options);
+  if (form !== null) {
+    const isLast = index === input.pointer.segments.length - 1;
+    return contentStep(walk, form, isLast, input.refs);
+  }
+  if (
+    isParameterList(input.pointer, index) ||
+    isExcludedOperation(input.pointer, index, owner, input)
+  ) {
+    return null;
+  }
+  return containerStep(walk, index, input);
+}
+
 function step(walk: TypedWalk, index: number, input: TypedWalkInput): TypedWalk | null {
   const { segments } = input.pointer;
   const segment = segments[index] as string;
@@ -156,20 +248,19 @@ function step(walk: TypedWalk, index: number, input: TypedWalkInput): TypedWalk
       ? nameStep(walk, segment, isLast, input)
       : keywordStep(walk, segment, isLast, input);
   }
+  if (walk.isFirstMediaType) {
+    return firstMediaTypeStep(walk, segment);
+  }
   if (segment === "schema" && isTypedAsSchema(input.pointer, index)) {
-    const owner = followRefs(walk.node, input.refs);
-    const schema = isJsonObject(owner) ? owner.schema : undefined;
-    // The container's type is its schema's type: an optional header stays optional.
-    const presence = walk.presence === "absent" ? "absent" : schemaPresence(schema, input.refs);
-    return { ...walk, node: schema, isSchema: true, presence };
+    return schemaStep(walk, input.refs);
   }
-  return isParameterList(input.pointer, index) ? null : containerStep(walk, index, input);
+  return documentStep(walk, index, input);
 }
 
 /** Walk the whole pointer; see the module comment. */
 export function typedWalk(input: TypedWalkInput): TypedWalkResult {
   const { pointer } = input;
-  const node = leadingNode(pointer, input.refs);
+  const { node, location } = leadingLocated(pointer, input.refs);
   const isSchema = startsInSchema(pointer);
   let walk: TypedWalk = {
     type: indexBy(
@@ -177,6 +268,7 @@ export function typedWalk(input: TypedWalkInput): TypedWalkResult {
       ...pointer.segments.slice(0, leadingSegmentsOf(pointer)),
     ),
     node,
+    location,
     isSchema,
     isName: false,
     presence: isSchema ? schemaPresence(node, input.refs) : "present",

package/src/application/transform/ref-type.ts

@@ -68,7 +68,8 @@ export function indexKeyword(type: IrType, segment: string, isLast: boolean): Ir
 }
 
 export function rootType(rootSegment: string, isDeep: boolean): IrType {
-  return irReference(isDeep ? `FlattenedDeepRequired<${rootSegment}>` : rootSegment);
+  const root = irReference(rootSegment);
+  return isDeep ? irReference("FlattenedDeepRequired", [root]) : root;
 }
 
 /**

package/src/application/transform/schema/access-flags.ts

@@ -30,7 +30,7 @@ function merged(left: AccessFlags, right: AccessFlags): AccessFlags {
  */
 function appliedFlags(
   schema: Schema | undefined,
-  context: SchemaContext,
+  context: Pick<SchemaContext, "refs">,
   seen: ReadonlySet<Schema>,
 ): AccessFlags {
   if (typeof schema !== "object" || schema === null || seen.has(schema)) {
@@ -52,7 +52,10 @@ function appliedFlags(
  * it count, as in openapi-typescript; with it, also those of the schemas its `$ref` and `allOf`
  * apply (upstream #1938).
  */
-export function propertyAccessFlags(value: Schema, context: SchemaContext): AccessFlags {
+export function propertyAccessFlags(
+  value: Schema,
+  context: Pick<SchemaContext, "options" | "refs">,
+): AccessFlags {
   if (typeof value !== "object") {
     return NO_FLAGS;
   }