@postman/sdk-config

@postman/sdk-config

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

SDK Config describes what to generate: SDK identity, API behavior, client behavior, package metadata, documentation, output, shared generation options, and one or more language targets. API source files, authentication, 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 the versioned entry point when creating an API payload. parseSdkConfigV1 validates unknown input, applies defaults, and returns the normalized SdkConfigV1 type.

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

const input: SdkConfigV1Input = {
  schemaVersion: 'sdk-config/v1',
  sdkName: 'Example SDK',
  sdkVersion: '1.0.0',
  api: {},
  client: { timeoutMs: 30_000 },
  package: {},
  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 sdkConfig: SdkConfigV1 = parseSdkConfigV1(input);

For validation without throwing, use the exported schema:

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.

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,
});

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:

• 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, package metadata, output, 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.