Introduction

The OpenSDK Specification (OSS) is a machine-readable companion file to an OpenAPI (or AsyncAPI) specification. Where OpenAPI describes what an API does — its endpoints, schemas, and authentication — OpenSDK describes how compliant SDK generators should turn that description into idiomatic, production-ready client libraries.

A single opensdk.yaml file, published alongside openapi.yaml, lets API providers declare their intended naming conventions, feature requirements, packaging metadata, reconciliation behavior, and governance rules across every language they officially support. Any compliant generator reads both files in one pass and produces SDKs that match the provider’s exact intent — no per-tool flags, no tribal knowledge, no drift.

The Problem

OpenAPI solved API documentation. It did not solve SDK generation.

Today, every API provider that ships official SDKs must separately configure each generator (OpenAPI Generator, Fern, Speakeasy, hand-rolled tools, etc.) through a mix of CLI flags, config files, and Mustache template overrides. The result is inconsistent:

• The Python SDK uses camelCase field names while the Go SDK uses PascalCase on the same resource
• The TypeScript client silently drops retry logic the Java client includes
• The Terraform provider has reconciliation semantics no other language shares

Consumers fare no better. A developer writing an integration must read provider documentation to discover that the “official” Go SDK requires 17 specific openapi-generator flags, or that the TypeScript SDK was generated with a private fork of a template set.

OpenSDK closes this gap. It is the missing layer between describing an API and producing a developer platform.

Design Principles

Separate but linked. opensdk.yaml is a distinct file, not embedded in openapi.yaml. It references the OpenAPI spec so generators can load both in one pass. This keeps concerns separated and allows the two files to version independently.

Declarative, not imperative. OpenSDK describes outcomes — “use snake_case for Python fields,” “always emit retry logic with exponential backoff,” “generate Terraform-style reconcile functions for Go” — rather than mandating specific templates or generator internals. Generators remain free to implement these outcomes in their own way.

Multi-language by default. A single opensdk.yaml covers all officially supported languages. Generators process only the targets relevant to them and silently skip targets they don’t support.

Governance built in. Validation rules, breaking-change policies, and reconciliation semantics are first-class citizens, not afterthoughts.

Versioned and extensible. The spec uses semantic versioning and x- extension fields (mirroring OpenAPI’s own conventions) so it can evolve without breaking existing generators.

Quick Start

The smallest valid opensdk.yaml needs only three fields:

opensdk: "1.0.0"

openapi:
  $ref: "./openapi.yaml"

sdk:
  name: "my-api"
  version: "1.0.0"

Generators receiving only this file apply their own idiomatic defaults for everything omitted. Add more as your needs grow.