@postman/sdk-config

@postman/sdk-config

Shared, runtime-validated public and internal configuration contracts for Postman's SDK generation pipeline.

This package is the source of truth for the customer-facing SdkConfig and internal SdkConfigIr. It is intended for sdk-gen-core, sdk-gen-api, Postman and Fern CLIs, and translators that normalize producer-specific configuration before generation.

Install

The package is configured as a restricted package in the @postman npm scope.

npm install @postman/sdk-config

Use

Use SdkConfigV1 for customer-authored, potentially multi-target generation configuration:

import { parseSdkConfigV1, type SdkConfigV1 } from '@postman/sdk-config/sdk-config/v1';

const sdkConfig: SdkConfigV1 = parseSdkConfigV1(untrustedInput);

Use SdkConfigIrV1 only for the normalized, single-target internal generator contract:

import { parseSdkConfigIrV1, type SdkConfigIrV1 } from '@postman/sdk-config/sdk-config-ir/v1';

const sdkConfigIr: SdkConfigIrV1 = parseSdkConfigIrV1(untrustedInput);

The package also exposes @postman/sdk-config, @postman/sdk-config/sdk-config, and @postman/sdk-config/sdk-config-ir as convenient current-version entry points. Persisted payloads must still include the appropriate schemaVersion.

SdkConfigV1 does not accept source selection, server-owned fields, SdkConfigIrV1, or legacy Postman BuildParameters. See the SDK Config v1 reference for the boundaries and target precedence rules.

Both ESM import and CommonJS require consumers are supported.

Project layout

src/
  sdk-config-domain/
    v1/                 # Portable field schemas shared by public config and internal IR
  sdk-config/
    v1/                 # Customer-facing multi-target schema and contract reference
  sdk-config-ir/
    v1/                 # Versioned schema, inferred types, and contract reference
tests/
  fixtures/
    sdk-config/v1/      # Canonical public configuration payloads
    sdk-config-ir/v1/   # Canonical portable payloads
  sdk-config/v1/        # Public contract and export tests
  sdk-config-ir/v1/     # Contract behavior tests
docs/
  migration.md          # sdk-gen-core adoption sequence

Develop

Requires Node.js 24 or newer. If you use nvm, run nvm use from the repository root.

npm install
npm run check
npm pack --dry-run

npm run check verifies formatting, linting, TypeScript, tests, and the dual-format package build.

Versioning and publishing

• npm access is restricted; do not set package.json private: true, because npm would refuse to publish it.
• Additive v1 fields require a package minor version and a consumer-first rollout because v1 uses strict runtime objects: an older consumer rejects fields it does not know.
• Breaking wire changes get a new schema directory and discriminator such as sdk-config/v2 or sdk-config-ir/v2.
• Keep the previous version exported while consumers migrate.

Manual release process

Release automation is intentionally deferred while the tagging and publishing process is reviewed with Postman's security team. Until that process is established, use the following manual release procedure. The commands use 1.1.0 as an example; replace it consistently with the version being released.

1. Prepare a release branch from develop

Normal feature pull requests target develop. Start the release from an up-to-date develop branch, update the version without creating a tag, and run the complete check suite:

git switch develop
git pull --ff-only origin develop
git switch -c release/v1.1.0
npm version 1.1.0 --no-git-tag-version
npm run check
git add package.json package-lock.json
git commit -m "release: v1.1.0"
git push -u origin release/v1.1.0

Open a pull request from release/v1.1.0 into main. Review the version change, wait for required checks and approvals, and merge it. The release branch isolates the version bump and preserves the exact develop snapshot being reviewed, while work can continue independently on develop.

2. Merge main back into develop

The publishing workflow requires the tagged commit to be in the history of the repository's default branch, develop. After the release pull request is merged, create a synchronization branch from the latest develop and merge the released main into it:

git fetch origin
git switch -c chore/merge-main-after-v1.1.0 origin/develop
git merge --no-ff origin/main -m "Merge main back to develop after v1.1.0"
git push -u origin chore/merge-main-after-v1.1.0

Open a pull request from chore/merge-main-after-v1.1.0 into develop, wait for its checks, and use Create a merge commit to merge it. Do not squash or rebase this pull request: the original main commit must remain in develop's ancestry for the publishing workflow's validation. The temporary branch can then be deleted safely.

3. Create the release tag from main

After the synchronization pull request is merged, update your local main and verify that package.json contains the version you are about to tag:

git switch main
git pull --ff-only origin main
node -p "require('./package.json').version"

Create the signed tag and dispatch the Package Release workflow with the tag as its explicit input:

npm run release -- v1.1.0

The release script requires a clean, up-to-date main, verifies that the package version matches the tag and that the commit is already contained in main and develop, creates and verifies a signed, annotated tag, pushes it, and dispatches .github/workflows/npm-publish.yml with tag=v1.1.0. The workflow independently rechecks main ancestry before calling the shared publisher, which verifies develop ancestry and the tag signature. Explicit dispatch avoids duplicate publish runs and keeps retries tied to the immutable tag. In GitHub, open Actions → Package Release and confirm the dispatched run succeeds.

If publishing fails after the tag has been created, do not delete, move, or recreate the tag. After the underlying problem is fixed, run the same command again. The script verifies and reuses the existing tag before dispatching another run. You can also use Actions → Package Release → Run workflow and enter the existing tag, such as v1.1.0.

See the SDK Config IR v1 reference for the complete contract.