@postman/sdk-config

@postman/sdk-config

Build and validate SDK Config documents for SDK Generation API requests.

SDK Config describes what to generate: API source provenance, SDK identity, API behavior, client behavior, package metadata, documentation, output, shared generation options, optional publishing credentials/signing material, and one or more language targets. The materialized API source bytes, idempotency, and transport metadata belong to the SDK Generation API request rather than the SDK Config document.

Install

npm install @postman/sdk-config

Node.js 24 or newer is required. Both ESM and CommonJS are supported.

Create and validate an SDK Config

Use validateSdkConfigV1 for a customer-authored document. Validation preserves omitted properties so persisted configuration is not populated with runtime defaults.

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

const input: SdkConfigV1Input = {
  schemaVersion: 'sdk-config/v1',
  sdkName: 'Example SDK',
  sdkVersion: '1.0.0',
  source: {
    specs: [{ id: 'example', type: 'openapi', path: './openapi.yml' }],
  },
  client: { timeoutMs: 30_000 },
  output: { delivery: 'zip', fileName: 'example-typescript.zip' },
  docs: { includeApiReference: true },
  generation: { includeWatermark: true },
  targets: [
    {
      language: 'typescript',
      generatorVersion: '1.2.3',
      package: { packageName: '@example/sdk' },
      generation: { packageManager: 'pnpm', testFramework: 'vitest' },
    },
  ],
};

const document: SdkConfigV1Document = validateSdkConfigV1(input);
const sdkConfig: SdkConfigV1 = parseSdkConfigV1(document);

Use parseSdkConfigV1 when entering the runtime boundary and materializing the shared domain defaults. For validation without throwing, use the exported schema:

Empty top-level api, client, package, docs, and generation blocks may be omitted from the customer document. Runtime parsing materializes those blocks and their versioned defaults.

import { sdkConfigV1Schema } from '@postman/sdk-config/sdk-config/v1';

const result = sdkConfigV1Schema.safeParse(input);
if (!result.success) {
  console.error(result.error.issues);
}

SDK Config objects are strict. Unknown fields, duplicate language targets, incompatible package publication settings, and non-exact generator versions are rejected. Publishing credentials and signing material may be provided under output.publish.credentials, Maven output.publish.signature, or output.github.credentials; these fields can contain raw secrets and must be handled accordingly by clients and servers.

SdkConfigV1 accepts customer-facing local source paths and HTTP(S) source URLs, but not server-owned signed URLs or artifact metadata. See the SDK Config v1 reference for source materialization and target precedence rules.

Use SDK Config in an SDK Generation API request

An SDK Generation API request combines three kinds of data:

• Request metadata describing the API input and generation targets.
• A source archive containing the API definition files.
• One SDK Config JSON payload for each request target that uses payloadKind: "sdk-config-v1".

The payload filename must match its target ID: <targetId>.json.

const targetId = 'typescript-sdk';
const request = {
  protocolVersion: 2,
  apiName: 'Example API',
  idempotencyKey: crypto.randomUUID(),
  apiInputs: [{ id: 'default', specIndexes: 'all' }],
  targets: [
    {
      targetId,
      apiInputId: 'default',
      language: 'typescript',
      sdk: {
        name: sdkConfig.sdkName,
        version: sdkConfig.sdkVersion,
        ...(sdkConfig.apiVersion === undefined ? {} : { apiVersion: sdkConfig.apiVersion }),
      },
      fernGenerator: { id: 'typescript-generator', version: '1.2.3' },
      payloadKind: 'sdk-config-v1',
      package: sdkConfig.targets[0]?.package,
      requestedOutput: { type: 'download' },
    },
  ],
};

const form = new FormData();
form.append('request', JSON.stringify(request));
form.append('sources', sourceArchive, 'sources.tar.gz');
form.append(
  'payloads',
  new Blob([JSON.stringify(sdkConfig)], { type: 'application/json' }),
  `${targetId}.json`,
);

const response = await fetch('https://api.example.com/sdk-generations', {
  method: 'POST',
  headers: { Authorization: `Bearer ${accessToken}` },
  body: form,
});

Before submitting the request, the client resolves every SDK Config source path or URL and places the exact bytes in the source archive. The endpoint URL, authentication scheme, source archive format, and response shape are defined by the SDK Generation API provider.

This request form supports downloaded archives. Its effective SDK Config output must be { "delivery": "zip" } without publication settings, and requestedOutput must be { "type": "download" }.

Keep request targets consistent

For each request target, the API request and matching SDK Config target must agree on:

• language
• effective SDK name and version
• API version, when present
• generator version, when generatorVersion is present in SDK Config
• every package property included in the API request; the request may omit package properties
• ZIP output without publication settings, paired with a download request

Root package properties are inherited by each target and overridden by target package properties. A target output replaces the root output; it is not merged with it.

Generation file paths

These SDK Config values are interpreted as file paths during generation:

• source.specs[].path
• source.specs[].overlays[]
• source.specs[].overrides[]
• generation.customQueryPaths[]
• generation.workflows[].path
• generation.hooks.source.location when source.type is path
• generation.customCode.source.location when source.type is path

Each value must be a relative path and cannot contain a .. path segment. Absolute POSIX paths, Windows drive paths, UNC paths, and parent-directory traversal are rejected during validation. URL source locations are not treated as file paths.

Multiple targets

An SDK Config can describe several language targets. Shared api, client, docs, and generation settings apply to every target. SDK identity, client settings, documentation, package metadata, output, common generation settings, and language-specific generation settings can be overridden per target.

Each language can appear only once. When sending a multi-target SDK Config to an SDK Generation API, attach the config under each request target that should select its matching language configuration.

Supported target languages are typescript, python, java, kotlin, go, csharp, php, ruby, rust, swift, cli, mcp, and terraform.