@postman/sdk-config 0.0.3 → 0.1.0

package/src/sdk-config-ir/v1/README.md

@@ -63,7 +63,8 @@ Examples of the boolean rule:
 
 - Boolean: `generation.webSockets`, `generation.multipleResponses`.
 - Configurable feature: `client.retry`, `client.tokenRefresh`, `docs.snippets`,
-  `generation.analytics`, `generation.hooks`, `generation.streams`, and `generation.wireTests`.
+  `generation.analytics`, `generation.hooks`, `generation.streams`, `generation.wireTests`, and
+  `generation.unitTests`.
 
 ## Cross-origin deduplication decisions
 
@@ -182,10 +183,10 @@ Translators are responsible for alias resolution, unit conversion, and inverted
 | CLI pagination parameters / skills object                                               | `generation.language.cli.paginationParameters` / `skills` boolean       |
 | language authors, developers, homepage, and repository                                  | `package` metadata                                                      |
 
-`usesFormData` is derived from the API and is not configuration. The legacy `ai` flag,
-`generateMCP`, MCP language options, Terraform-provider options and plan modifiers, and Bash output
-are outside the SDK Config IR v1 target set and must be reported as unsupported. Commented-out
-custom-template and naming inputs were not restored as part of the normalized contract.
+`usesFormData` is derived from the API and is not configuration. The legacy `generateMCP` switch
+and Bash output are outside the SDK Config IR v1 target set and must be reported as unsupported;
+MCP and Terraform instead use explicit target languages. Commented-out custom-template and naming
+inputs were not restored as part of the normalized contract.
 
 ## Fern common migration map
 
@@ -203,6 +204,7 @@ audited on 2026-07-17. Counts guide the initial contract; they are not a permane
 | `api.environments`                                                          | `api.environments`                                 |                                        20+ |
 | `api.auth`, `api.auth-schemes`                                              | `api.auth`                                         |                                         27 |
 | `api.headers`                                                               | `api.headers`                                      |                                        11+ |
+| generator-group `audiences`                                                 | `api.audiences`                                    |              Absent selects all audiences. |
 | generator `inlinePathParameters`, `inline-path-parameters`, and API setting | `client.pathParameterStyle`                        |                   12 API; 1-3 per language |
 | generator `inlineFileProperties`, `inline-file-properties`                  | `client.filePropertyStyle`                         |                           1-3 per language |
 | `inline_request_params`                                                     | `client.requestParameterStyle`                     |                                   6 Python |
@@ -210,6 +212,7 @@ audited on 2026-07-17. Counts guide the initial contract; they are not a permane
 | timeout aliases in seconds or milliseconds                                  | `client.timeoutMs`                                 |                 Translator converts units. |
 | `skipResponseValidation`, Python `skip_validation`                          | `client.responseValidation`                        |                  Inverted; 12 TS, 8 Python |
 | `useDefaultRequestParameterValues` aliases                                  | `client.useDefaultRequestParameterValues`          |                                          1 |
+| `respectOptionalRequestBody`, `respect-optional-request-body`               | `client.respectOptionalRequestBody`                |     Not in the project snapshot; see below |
 | `enable-wire-tests`, `enableWireTests`, `generateWireTests`                 | `generation.wireTests`                             |                          1-15 per language |
 | WebSocket generation aliases                                                | `generation.webSockets`                            |                             3 TS, 3 Python |
 | `streamType`, `fileResponseType`                                            | `generation.streams`                               |                                       1 TS |
@@ -225,6 +228,7 @@ audited on 2026-07-17. Counts guide the initial contract; they are not a permane
 | registry output                                                             | `output.publish` plus `package` identity           |                 5-28 per registry language |
 | GitHub output                                                               | `output.delivery: "github"` and `output.github`    | Translator resolves Fern owner/repo forms. |
 | Fern README config                                                          | `docs.readme`                                      |  12 API names; 11 disabled-section configs |
+| `customReadmeSections`                                                      | `docs.readme.customSections`                       |     Not in the project snapshot; see below |
 | `includeApiReference`                                                       | `docs.includeApiReference`                         |                                      10 TS |
 
 The Rust language config was added after the initial audit. That audit compared existing Fern
@@ -234,6 +238,19 @@ versus `DateTime<Utc>` on every datetime field), `capitalizeInitialisms`, `featu
 `defaultFeatures`. Crate identity, client name, and package metadata deliberately stay on the
 shared fields.
 
+`docs.readme.customSections` came from that same generator-schema comparison. Nine Fern generators
+declare an identical `customReadmeSections` array of `{title, content}`, so it is a shared
+documentation concern rather than a language one. `title` is the section's identity: a derived
+section carrying the same title is replaced rather than duplicated. Fern's per-section `language`
+discriminator is dropped, because one IR document already describes one target.
+
+`client.respectOptionalRequestBody` came from the same comparison and postdates the project
+snapshot. Eight Fern generators honour it — Rust, Go, PHP, Ruby, both TypeScript generators, C# and
+Java — so it is shared client behavior. It stays undefaulted rather than defaulting to `false`:
+enabling it changes the signature of every endpoint whose body the API declares as not required, so
+absent must keep an existing SDK's signatures rather than assert a value the generator would then
+have to honour.
+
 Fern README endpoint strings such as `GET /users` are parsed into
 `{ "method": "GET", "path": "/users" }`; the legacy string shorthand is not part of the
 normalized contract.
@@ -243,19 +260,20 @@ normalized contract.
 These settings remain under `source.apiImportSettings` because they affect spec conversion rather
 than generated-language presentation.
 
-| Fern setting                              | Normalized field                     | Observed projects |
-| ----------------------------------------- | ------------------------------------ | ----------------: |
-| `respect-nullable-schemas`                | `respectNullableSchemas`             |                10 |
-| `title-as-schema-name`                    | `titleAsSchemaName`                  |                16 |
-| `coerce-enums-to-literals`                | `coerceEnumsToLiterals`              |                14 |
-| `idiomatic-request-names`                 | `idiomaticRequestNames`              |                12 |
-| `wrap-references-to-nullable-in-optional` | `wrapReferencesToNullableInOptional` |                 9 |
-| `coerce-optional-schemas-to-nullable`     | `coerceOptionalSchemasToNullable`    |                 9 |
-| `object-query-parameters`                 | `objectQueryParameters`              |                 9 |
-| `only-include-referenced-schemas`         | `onlyIncludeReferencedSchemas`       |                 4 |
-| `group-multi-api-environments`            | `groupMultiApiEnvironments`          |                 2 |
-| `path-parameter-order`                    | `pathParameterOrder`                 |                 2 |
-| `type-dates-as-strings`                   | `typeDatesAsStrings`                 |                12 |
+| Fern setting                              | Normalized field                     |             Observed projects |
+| ----------------------------------------- | ------------------------------------ | ----------------------------: |
+| `respect-nullable-schemas`                | `respectNullableSchemas`             |                            10 |
+| `title-as-schema-name`                    | `titleAsSchemaName`                  |                            16 |
+| `coerce-enums-to-literals`                | `coerceEnumsToLiterals`              |                            14 |
+| `idiomatic-request-names`                 | `idiomaticRequestNames`              |                            12 |
+| `wrap-references-to-nullable-in-optional` | `wrapReferencesToNullableInOptional` |                             9 |
+| `coerce-optional-schemas-to-nullable`     | `coerceOptionalSchemasToNullable`    |                             9 |
+| `object-query-parameters`                 | `objectQueryParameters`              |                             9 |
+| `only-include-referenced-schemas`         | `onlyIncludeReferencedSchemas`       |                             4 |
+| `group-multi-api-environments`            | `groupMultiApiEnvironments`          |                             2 |
+| `path-parameter-order`                    | `pathParameterOrder`                 |                             2 |
+| `type-dates-as-strings`                   | `typeDatesAsStrings`                 |                            12 |
+| `default-integer-format`                  | `defaultIntegerFormat`               | Importer defaults to `int32`. |
 
 ## Fern language-specific migration map
 
@@ -265,14 +283,15 @@ Only options that remain language-specific stay in `generation.language`.
 | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
 | TypeScript  | `packageManager` (1), `testFramework` (2), `allowCustomFetcher` (13), branded aliases (1), legacy exports (1), `useBigInt`, and positive `serdeLayer` from `noSerdeLayer` (8)                                | Namespace, validation, inline types, dependencies, wire tests, streams, WebSockets, pager/client names                                   |
 | Python      | Python/Pydantic versions, client filenames (13), Pydantic compatibility, frozen models (1), required optionals (2), union naming (1), field aliases (3), always-initialize optionals, TypedDict requests (3) | Package/module names, enum form, extra fields, response validation, request style, dependencies, timeout, layout, wire tests, WebSockets |
-| Java/Kotlin | Package layout (3), local dates (2), optional-nullable collapse (2), and Gradle settings (7)                                                                                                                 | Maven identity, namespace, names, forward-compatible enums, inline properties, dependencies, pager, wire tests                           |
-| Go          | Legacy complex models, union version (3), and legacy client options (1)                                                                                                                                      | Module/package identity, client name, inline properties, pager, wire tests                                                               |
-| C#          | Optional wrapper, simplified dictionaries (1), explicit namespaces (7), core namespace behavior (1), exception handler (5)                                                                                   | NuGet identity, namespace, class/error names, pager, wire tests                                                                          |
+| Java/Kotlin | Package layout (3), local dates (2), optional-nullable collapse (2), Gradle settings (7), and JVM async-client style                                                                                         | Maven identity, namespace, names, forward-compatible enums, inline properties, dependencies, pager, wire tests                           |
+| Go          | Legacy complex models, union version (3), legacy client options (1), smart casing, and the fern root-client constructor name                                                                                 | Module/package identity, client name, environments, inline properties, pager, wire tests                                                 |
+| C#          | Optional wrapper, simplified dictionaries (1), explicit namespaces (7), core namespace behavior (1), exception handler (5), and the experimental explicit-nullable-optional switch                           | NuGet identity, namespace, class/error names, pager, wire tests                                                                          |
 | PHP         | Property access (2) and generated client interfaces (1)                                                                                                                                                      | Composer identity, namespace, client/pager names, request style, dependencies, wire tests                                                |
 | Ruby        | Require paths (2)                                                                                                                                                                                            | Gem identity, client name, dependencies, pager, wire tests                                                                               |
 | Rust        | Datetime representation, initialism casing, and Cargo features/default-features                                                                                                                              | Crate identity, client name, and package metadata use shared fields.                                                                     |
-| Swift       | No retained language-specific options                                                                                                                                                                        | Shared generation behavior is sufficient for observed configs.                                                                           |
+| Swift       | Module name and the nullable-as-optional collapse                                                                                                                                                            | Client, environment and error naming use shared fields.                                                                                  |
 | CLI         | Pagination parameter names and the `skills` boolean                                                                                                                                                          | Go module and package identity use `package`.                                                                                            |
+| MCP         | Server identity, availability exclusions, tool filters and named toolsets, plus the TypeScript options                                                                                                       | npm package identity, client and serialization behavior                                                                                  |
 
 ## Removed and deferred legacy configuration
 
@@ -288,8 +307,8 @@ the migration.
   discriminant removal, schema-collision recovery, forward-compatible inference, default
   environment inference, const coercion, endpoint filters, example-depth controls, alias
   resolution, single-schema oneOf preservation, readonly/read variants, binary-response import
-  coercion, form encoding defaults, additional-properties defaults, inline-allOf, default integer
-  formats, discriminated-union inference, request-name disambiguation, and AsyncAPI message naming.
+  coercion, form encoding defaults, additional-properties defaults, inline-allOf,
+  discriminated-union inference, request-name disambiguation, and AsyncAPI message naming.
 - TypeScript: linter/formatter selection, consolidated type files, subpackage exports, and endpoint
   metadata.
 - Python: ORM/smart-union/coercion/wrapped-alias/positional-constructor/inheritance/validator
@@ -299,10 +318,10 @@ the migration.
   nullable annotations, and custom interceptors.
 - C#: union implementation switches, root-client access, generated error-type toggle, interceptor
   class, unified options, response-body redaction, solution format, and custom output paths.
-- Go: toolchain version, import aliases, custom constructor name, error-code layout, empty wrapper,
-  byte reader, getter, union-base deduplication, and root-request export switches.
+- Go: toolchain version, import aliases, error-code layout, empty wrapper, byte reader, getter,
+  union-base deduplication, and root-request export switches.
 - Ruby: custom client module and RuboCop switches.
-- Rust and Swift: all previously proposed language-specific switches had no observed customer use.
+- Rust: all previously proposed language-specific switches had no observed customer use.
 
 ### Observed but deliberately deferred as bespoke or low-use