@postman/sdk-config 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@postman/sdk-config",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Shared SDK configuration contracts and transformations for Postman SDK generation",
   "license": "UNLICENSED",
   "sideEffects": false,
@@ -48,7 +48,7 @@
     "url": "git+https://github.com/postman-eng/sdk-config.git"
   },
   "publishConfig": {
-    "access": "restricted"
+    "access": "public"
   },
   "engines": {
     "node": ">=24"

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

@@ -4,11 +4,30 @@
 describes portable generation intent and uses the discriminator `schemaVersion: "sdk-config/v1"`.
 
 ```ts
-import { parseSdkConfigV1, type SdkConfigV1 } from '@postman/sdk-config/sdk-config/v1';
-
-const config: SdkConfigV1 = parseSdkConfigV1(untrustedInput);
+import {
+  parseSdkConfigV1,
+  validateSdkConfigV1,
+  type SdkConfigV1,
+  type SdkConfigV1Document,
+} from '@postman/sdk-config/sdk-config/v1';
+
+// Validate a customer-authored document while preserving omitted properties.
+const document: SdkConfigV1Document = validateSdkConfigV1(untrustedInput);
+
+// Resolve domain defaults only when preparing a runtime configuration.
+const resolved: SdkConfigV1 = parseSdkConfigV1(document);
 ```
 
+`validateSdkConfigV1` is the correct boundary for persisted files, migration output, and request
+transport. It validates the same schema as `parseSdkConfigV1` but returns the sparse authored
+document, so omitted options remain omitted. `parseSdkConfigV1` is the runtime-resolution boundary:
+it materializes shared domain defaults needed while expanding a target into `SdkConfigIrV1`.
+
+This separation is intentional. A migration must not invent `sdkVersion`, `apiVersion`, or other
+default-valued settings that were absent from the legacy Fern configuration. An explicit value—even
+one equal to the current default—must remain distinguishable from omission so future default changes
+do not silently alter customer intent.
+
 ### Convert a Fern generator group
 
 The Fern CLI can convert its resolved in-memory generator group without serializing or reparsing
@@ -20,6 +39,9 @@ import { mapFernConfigToSdkConfigV1 } from '@postman/sdk-config/sdk-config/v1';
 
 const { sdkConfig, unsupportedFields } = mapFernConfigToSdkConfigV1({
   apiName: definition.rootApiFile.contents.name,
+  source: {
+    specs: [{ id: 'payments', type: 'openapi', path: './openapi.yml' }],
+  },
   apiVersion: definition.specVersion,
   sdkVersion,
   group: {
@@ -35,28 +57,39 @@ representation are returned in `unsupportedFields`; each issue includes a code,
 severity, reason, suggested manual action, and the SDK Config destination when one exists.
 `FernConfigMappingError.issues` uses the same structure for missing information and other fatal
 cases. Generation must not recover omitted values from legacy configuration. Differing
-target-specific values for a shared SDK Config block are rejected because combining them would
-change behavior. Optional `api` enrichment may be supplied after Fern's definition or IR has already
-been lowered into the public API shape.
+target-specific values are retained as sparse target overrides when the public shape can represent
+them. Optional `api` enrichment may be supplied after Fern's definition or IR has already been
+lowered into the public API shape. Credentials and signing material remain outside SDK Config; the
+mapper reports one target-level diagnostic when a Fern output contains them without logging their
+values.
 
 ## Contract boundaries
 
 `SdkConfigV1` is distinct from both existing configuration contracts:
 
-- `SdkConfigV1` is customer-facing, may contain multiple one-language targets, and does not select
-  the API source. A client or sdk-gen-api supplies a collection ID, specification ID, or uploaded
-  file separately.
+- `SdkConfigV1` is customer-facing, may contain multiple one-language targets, and explicitly names
+  the local paths or HTTP(S) URLs of the API specifications it configures. A source may be one spec
+  or an ordered multi-spec set, with optional namespaces, overlays, overrides, and API import
+  settings.
 - `SdkConfigIrV1` is the normalized, single-target internal input consumed by sdk-gen-core. A server
-  expands one `SdkConfigV1` into one IR document per target and supplies source and operational
-  metadata.
+  expands one `SdkConfigV1` into one IR document per target, uploads the declared source files, and
+  replaces customer paths with internal `specUrl` values without changing the IR shape.
 - The legacy Postman configuration (`BuildParameters`) is an older producer-specific input. It is
   not accepted by `parseSdkConfigV1`; legacy translators normalize it independently.
 
-The public schema deliberately has no `source`, `compatibility`, source-origin, artifact ID, signed
-URL, S3 location, credential-resolution, or server-generated publishing control fields. Unknown
-fields are rejected at every object boundary. Portable API, client, documentation, package, and
-language field schemas come from a neutral shared domain layer to prevent drift; the public and
-internal envelopes and their operational extensions remain separate explicit allowlists.
+Each public source contains exactly one customer-owned locator: `path` for a local file or `url` for
+an HTTP(S) resource. A generation client must materialize the selected resource and upload the exact
+bytes for the build; the server replaces the customer locator with an internal signed `specUrl` in
+SDK Config IR. Customer URLs never become generator fetch URLs. Signed URLs, S3 locations, and
+server-generated artifact metadata are not valid public locators. The public schema deliberately has
+no `compatibility`, source-origin, artifact ID, credential-resolution, or server-generated
+publishing control fields. Unknown fields are rejected at every object boundary. Portable API,
+client, documentation, package, source settings, and language field schemas come from a neutral
+shared domain layer to prevent drift; the public and internal envelopes and their operational
+extensions remain separate explicit allowlists.
+
+Source `path`, `overlays`, and `overrides` values must be relative paths without parent-directory
+segments. Absolute paths and `..` traversal are rejected at validation time.
 
 ## Shape
 
@@ -65,17 +98,26 @@ internal envelopes and their operational extensions remain separate explicit all
   "schemaVersion": "sdk-config/v1",
   "sdkName": "Acme SDK",
   "sdkVersion": "1.0.0",
+  "source": {
+    "specs": [{ "id": "payments", "type": "openapi", "url": "https://example.com/openapi.yml" }]
+  },
   "api": {},
   "client": {},
   "package": { "description": "Acme API SDK" },
   "output": { "delivery": "zip" },
   "docs": {},
-  "generation": { "includeWatermark": true },
+  "generation": {
+    "includeWatermark": true,
+    "naming": { "smartCasing": true, "smartCasingDigitWordBoundary": false }
+  },
   "targets": [
     {
       "language": "typescript",
       "package": { "packageName": "@acme/sdk" },
-      "generation": { "packageManager": "pnpm" }
+      "generation": {
+        "packageManager": "pnpm",
+        "namespaceExportName": "AcmeSDK"
+      }
     },
     {
       "language": "python",
@@ -92,6 +134,20 @@ Each target has exactly one `language`. A language may occur only once, so both
 targets and differing targets that conflict on the same language are rejected. `generatorVersion`
 is an optional target-only exact semantic version.
 
+Field placement follows ownership rather than whichever Fern generator happens to appear first:
+
+- API configuration and API version are global.
+- Client, documentation, and common generation settings are global when identical across every
+  target; differing values become sparse target overrides.
+- Package identity, output delivery, publication, repositories, generator version, and
+  language-specific generation settings remain on their target.
+- SDK name and version use a global baseline with optional target overrides.
+
+The root `output` is therefore optional. It is useful as an explicitly authored baseline, but every
+target must have an effective output either from that baseline or from its own `output` block. Fern
+migration writes output directly on each target because repositories and publication registries are
+properties of the generated language artifact.
+
 ## Supported languages
 
 SdkConfig v1 is language-agnostic across every sdk-gen-core target available when this contract was
@@ -99,7 +155,7 @@ defined. Each language has an explicitly allowlisted `generation` shape:
 
 | Language   | `language` value | Representative target setting |
 | ---------- | ---------------- | ----------------------------- |
-| TypeScript | `typescript`     | `packageManager`              |
+| TypeScript | `typescript`     | `namespaceExportName`         |
 | Python     | `python`         | `pythonVersion`               |
 | Java       | `java`           | `includeKotlinSnippets`       |
 | Kotlin     | `kotlin`         | `asyncStyle`                  |
@@ -122,14 +178,26 @@ When a server expands the public config into single-target IR documents, it appl
 
 | Configuration           | Rule                                                                                                            |
 | ----------------------- | --------------------------------------------------------------------------------------------------------------- |
-| `api`, `client`, `docs` | Shared unchanged by every target; no target override exists.                                                    |
-| Root `generation`       | Shared generation behavior for every target.                                                                    |
-| Target `generation`     | Language-specific settings for that target; it supplements the disjoint shared settings.                        |
+| `api`                   | Shared unchanged by every target; no target override exists.                                                    |
+| `client`, `docs`        | Sparse target properties recursively override root properties; omitted properties inherit. Arrays replace.      |
+| Root `generation`       | Shared generation behavior inherited by every target.                                                           |
+| Target `generation`     | Sparse common generation properties override root values; language-specific properties configure that target.   |
 | `sdkName`, `sdkVersion` | A target value wins; otherwise the root value is inherited.                                                     |
 | `package`               | Target properties override root properties; omitted properties inherit. Arrays replace rather than concatenate. |
-| `output`                | A target block replaces the complete root output block; otherwise the root block is inherited.                  |
+| `output`                | An optional root baseline is inherited; a target block replaces it completely. Every target must resolve one.   |
 | `apiVersion`            | Shared unchanged by every target.                                                                               |
 
+Target `client`, `docs`, and common `generation` blocks are intentionally sparse. This allows one
+multi-language document to retain a shared baseline while expressing a Fern setting that differs
+between generators—for example, a Python-specific client name. Nested objects inherit recursively,
+while an explicitly supplied array replaces the inherited array.
+
+An integration may also supply operational values at generation time. Those request values take
+precedence over the persisted SDK Config for fields the integration exposes, such as SDK name,
+SDK version, API version, package settings, generator version, and output intent. The SDK Config
+continues to provide every field that the request does not override. Schema/domain defaults are
+applied only after this merge, when the single-target `SdkConfigIrV1` is parsed.
+
 Package publication requirements are validated after applying package and output precedence. For
 example, a TypeScript target publishing to npm may inherit a root `packageName`, while a Python
 target must replace an inherited npm output with a PyPI-compatible output.

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

@@ -209,6 +209,7 @@ audited on 2026-07-17. Counts guide the initial contract; they are not a permane
 | generator `inlineFileProperties`, `inline-file-properties`                  | `client.filePropertyStyle`                         |                           1-3 per language |
 | `inline_request_params`                                                     | `client.requestParameterStyle`                     |                                   6 Python |
 | `customPagerName`, `custom-pager-name`, `custom_pager_name`                 | `generation.naming.pagerName`                      |                           2-5 per language |
+| `smart-casing`, `smart-casing-digit-word-boundary`                          | `generation.naming`                                |        Preserved only when explicitly set. |
 | 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 |
@@ -281,10 +282,10 @@ Only options that remain language-specific stay in `generation.language`.
 
 | Language    | Fern fields retained in language config                                                                                                                                                                      | Shared mappings lifted out                                                                                                               |
 | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| 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                                   |
+| TypeScript  | `packageManager` (1), `testFramework` (2), `namespaceExportName`, `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), 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                                                 |
+| Go          | Legacy complex models, union version (3), legacy client options (1), and the fern root-client constructor name                                                                                               | Module/package identity, client name, environments, smart casing, 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                                                                               |