Codegen Rules

Cross-language governance — validation gates, breaking change policy, output structure, and field exclusions.

codegenRules apply across all language targets. They express governance constraints that generators MUST enforce before and during code emission.

codegenRules:
  validation:
    - rule: no-unnamed-operations
      severity: error
  reconciliation:
    mode: declarative
    ignoreDrift: [status, createdAt]
    immutableFields: [id, region]
  breakingChangePolicy: major-version-bump
  sdkVersioning: semver-manual
  outputStructure: by-tag
  ignoreFields:
    - __debug
    - _internalOnly

Validation Rules

Generators MUST evaluate validation rules against the source OpenAPI spec before emitting code.

Rules with severity: error MUST halt generation.
Rules with severity: warn SHOULD print a warning but MAY continue.
Rules with severity: info are informational only.

codegenRules:
  validation:
    - rule: no-unnamed-operations
      severity: error
      message: "Every operation must have an operationId."
    - rule: required-tags
      severity: error
    - rule: no-inline-schemas
      severity: warn
    - rule: custom
      severity: error
      customRuleUrl: "https://acme.com/rules/no-empty-tags.js"

Built-in Rules

Rule	Description
`no-unnamed-operations`	Every operation must have an `operationId`. Anonymous operations cannot be mapped to SDK methods.
`required-tags`	Every operation must have at least one tag for SDK grouping.
`no-inline-schemas`	Schemas must be defined in `components/schemas`, not inline. Inline schemas cannot be named and may break across regenerations.
`required-descriptions`	Operations and schemas must have descriptions.
`no-deprecated-without-successor`	Deprecated operations should reference their replacement via `x-successor`.
`no-empty-responses`	Every operation must declare at least one response.
`custom`	A custom rule script loaded from `customRuleUrl`.

Breaking Change Policy

Controls how generators handle breaking changes detected between the current spec and the previous version.

Value	Behavior
`major-version-bump`	Generators increment the major version. May include both old and new symbols during a transition period.
`deprecate-first`	Old symbol is marked deprecated and kept for one release cycle before removal.
`warn-only`	Generators warn but do not modify versioning or symbols.

SDK Versioning Strategy

Value	Description
`semver-from-openapi`	SDK version is derived from the OpenAPI spec’s `info.version` field.
`semver-manual`	SDK version is taken from `sdk.version` in `opensdk.yaml`.
`date-based`	SDK version is a date stamp (e.g. `2026.04.01`).

Output Structure

Controls how generated files are organized on disk.

Value	Description
`flat`	All generated files in a single directory.
`by-tag`	One directory per OpenAPI tag.
`by-resource`	One directory per top-level resource noun.
`by-operation`	One file per operation.

Global Field Exclusions

Fields in ignoreFields are stripped from all generated models across every language target.

codegenRules:
  ignoreFields:
    - __debug
    - _internalOnly
    - x_internal_id

This is useful for internal or debug fields that appear in your API schema but should never be exposed in public SDKs.