File Format

How opensdk.yaml is structured at the top level — required fields, file format, and schema reference.

Format

OpenSDK files MUST be valid YAML 1.2 or JSON. The canonical file name is opensdk.yaml (or opensdk.json). Files may be hosted at a URL or referenced from a registry.

A generator MUST validate the file against the published JSON Schema before processing it:

https://opensdks.org/schema/v1/opensdk.schema.json

Add the following comment to the top of any opensdk.yaml for inline validation and autocomplete in VS Code and any YAML LSP-capable editor:

# yaml-language-server: $schema=https://opensdks.org/schema/v1/opensdk.schema.json

Top-Level Fields

Field	Required	Type	Description
`opensdk`	✅	string	Semantic version of the OpenSDK Specification in use.
`openapi`	✅	object	Reference to the source OpenAPI or AsyncAPI spec.
`sdk`	✅	object	SDK-level metadata (name, version, license, authors).
`languages`	—	array	Per-language codegen configuration.
`codegenRules`	—	object	Cross-language governance rules.
`extensions`	—	object	Arbitrary `x-` extension fields.

`opensdk`

A string matching MAJOR.MINOR.PATCH. Generators MUST reject files whose major version they do not support.

opensdk: "1.0.0"

`openapi`

openapi:
  $ref: "./spec/openapi.yaml"   # relative path or absolute URL
  version: "3.1"                # optional; generators may enforce this

Supported version values: 3.0, 3.1, asyncapi-2, asyncapi-3.

`sdk`

sdk:
  name: "acme-api"
  version: "2.1.0"
  license: "Apache-2.0"
  homepage: "https://docs.acme.com/sdk"
  description: "Official SDKs for the Acme Platform API"
  repository: "https://github.com/acme/acme-sdks"
  authors:
    - name: "Acme Platform Team"
      email: "platform@acme.com"
      url: "https://acme.com"

Field	Required	Description
`name`	✅	Canonical SDK name. Used as base for package names across languages.
`version`	✅	Semantic version of the SDK being generated.
`license`	—	SPDX license identifier (e.g. `MIT`, `Apache-2.0`).
`homepage`	—	URL to SDK homepage or documentation.
`description`	—	Short human-readable description.
`repository`	—	URL to SDK source repository.
`authors`	—	Array of `{ name, email?, url? }` objects.