Changelog

(fix): Scope the namespaced-errors OpenAPI setting to the spec that enables it, and only honor an explicit x-fern-sdk-namespace on the response object. Previously enabling the setting on one spec applied it to every spec in the API, and errors whose body schema lived in a namespace were moved into that namespace.

(feat): Add the namespaced-errors OpenAPI setting (default false). When enabled, an error whose response object (components.responses[...]) or body schema carries x-fern-sdk-namespace is declared in, and its shared-error conflict detection is scoped to, that namespace instead of the endpoint’s. This lets each namespace get its own typed TooManyRequestsError etc. while endpoints and other types stay at the root.

(fix): Revert the namespace-scoped shared-error collapse (#17619) and the case-insensitive namespace/tag flattening (#17643) in the OpenAPI importer. Shared errors are again compared API-wide by status code, and an operation tag that only matches the spec namespace case-insensitively is again treated as a sub-group.

(fix): Fall back to an OpenAPI parameter’s inline schema description when the parameter itself has no description, so query, header, and path parameter docs appear in generated API references.

(fix): When an OpenAPI spec has namespace set, an operation tag that matches the namespace case-insensitively (e.g. tag Video with namespace: video) is now treated as the namespace itself instead of creating a nested video.video sub-package.

(feat): Add fern sdk migrate to create Postman SDK Config v1 from existing Fern SDK groups, including the exact single- or multi-spec API source paths. Repeat --group to consolidate groups that resolve to the same API schema and source configuration into one multi-language configuration.

(fix): When importing OpenAPI specs with namespace set, shared SDK errors are now collapsed to unknown per namespace instead of across the whole API. A status code that has a different body schema in one namespace no longer degrades the typed error body in other namespaces.

(fix): Supply resolved API source archives when fern sdk preview routes generation through sdk-gen-api, and accept the empty default OpenAPI audience filter during SDK Config source validation.

(internal): Select sdk-gen-api payload routes before generation work, preserve legacy Fern runtime bundles for pre-cutover targets, and require SDK Config v1 at or after each generator’s cutover version. Reject incompatible legacy configuration with an actionable fern sdk migrate instruction before source preparation or remote mutations, while preparing deterministic, deduplicated source archives for compatible targets.

(feat): Add the any-of-sibling-properties-as-object OpenAPI setting. When enabled, a schema that declares properties alongside an anyOf whose branches only re-declare some of those same properties as required is converted as the object it declares, rather than as an undiscriminated union. Per JSON Schema such an anyOf is an “at least one of” constraint over sibling properties, not a set of variants, so converting it to a union discards the declared properties and makes the fields mutually exclusive — a request body setting two of them silently sent only one.

(fix): The warning for auth-schemes declared without api.auth now fires on fern generate and fern check, not only fern check --from-openapi. It was emitted from OSSWorkspace.getIntermediateRepresentation, a branch reached only when --from-openapi is passed; fern generate and plain fern check go through toFernWorkspace and saw nothing. Since the whole point is that this misconfiguration is otherwise silent — valid YAML, clean check, successful generation, and a client reading an environment variable the user never configured — the warning was unreachable on exactly the paths where it was needed. Both entry points now emit it, at most once per workspace.

(feat): Add FERN_RUNTIME_ENV_VARS, which defers the listed environment variables past generation for self-hosted docs. Instead of being substituted with their build-time value, ${APP_SERVER} is rewritten to a FERN_SELF_HOSTED_ENV_APP_SERVER placeholder that the self-hosted container resolves on every request, so a single generated image can serve deployments that differ only in those values.

(fix): Preserve deprecated/x-fern-availability on OpenAPI object properties whose value is a $ref (or a single-$ref allOf). Previously availability was only read off inline schemas, so a request body property referencing a deprecated component schema rendered without a Deprecated badge, while the equivalent query parameter did.

x-fern-availability written alongside a $ref now overrides the referenced schema’s availability, so a property can opt out of an inherited deprecated.

(fix): Warn when generators.yml declares auth-schemes but no api.auth to select them. The workspace only reads the auth-schemes block when api.auth is set, so declaring schemes without it silently discards the whole block — env: overrides included — before the importer sees it. Auth is then re-derived from the spec’s securitySchemes, which carries no environment variable, and each generator falls back to its own default name (the CLI generator to <BINARY>_TOKEN). Nothing is invalid, so fern check stayed clean and generation succeeded while producing a client that read an environment variable the user never configured. The warning names the schemes being dropped and the auth: line that applies them.

(fix): Fix fern check and docs previews failing with an uncaught error (e.g. “Expected one of … Received [object Object]”) when the broken-links rule builds an API definition for an api section. The rule now resolves the API definition the same way the docs build does, skips link validation for an API it cannot load, and a rule that throws mid-validation is reported as a violation honoring its configured severity instead of aborting the command.

(fix): Convert a GraphQL interface to its own set of fields and record each implements clause on the implementing type, so docs can list an interface’s fields and the types that implement it.

(fix): Don’t document GraphQL operation-namespace types (e.g. a Mutation.checkout: CheckoutMutations grouping type) as types of their own. Their fields are already documented as operations, so a type page for them duplicated every field and argument on the referenced types’ pages.

(internal): Send generator-compatible Fern runtime bundles with sdk-gen-api build requests.

(fix): Publish the configured default locale as the docs manifest locale key instead of always using “en”.

(feat): You can now keep your redirects in their own files instead of listing them all in docs.yml. Point redirects at one file or several, and Fern combines them in the order you list them.

(chore): Fix stale blog changelog-slug rule test expectations after the blog feed slug allowlist change.

(feat): Add a blog navigation item as an alias for changelog navigation.

(fix): Accept blog, blogs, and posts changelog slugs for feeds.

(chore): Add snapshot coverage for OAuth client credentials with a custom token header and prefix.