@postman/sdk-config

@postman/sdk-config

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

This package is the source of truth for 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

Prefer the versioned entry point at transport and persistence boundaries:

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

const sdkConfigIr: SdkConfigIrV1 = parseSdkConfigIrV1(untrustedInput);

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

Both ESM import and CommonJS require consumers are supported.

Project layout

src/
  sdk-config-ir/
    v1/                 # Versioned schema, inferred types, and contract reference
tests/
  fixtures/
    sdk-config-ir/v1/   # Canonical portable payloads
  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-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 a signed, annotated tag on the checked-out main commit, verify it locally, and push it:

git tag -s v1.1.0 -m "Release v1.1.0"
git tag -v v1.1.0
git push origin v1.1.0

Pushing a tag matching v*.*.* automatically triggers the Package Release workflow defined in .github/workflows/npm-publish.yml. In GitHub, open Actions → Package Release and confirm the tag-triggered 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, open Actions → Package Release → Run workflow and enter the existing tag, such as v1.1.0, to retry it.

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