Generator Conformance

A generator is considered compliant with this specification if it meets all of the following requirements:

1. Accepts opensdk.yaml (or opensdk.json) as a primary input alongside an OpenAPI spec.
2. Validates the file against the published JSON Schema before processing.
3. Processes all languages entries for targets it supports and silently skips targets it does not.
4. Respects all style, features, and codegenRules fields it claims to support.
5. Documents which fields and values it supports in its own conformance matrix (see below).
6. Passes the OpenSDK conformance test suite (forthcoming).

Partial conformance is acceptable and encouraged. Generators SHOULD publish a conformance matrix.

Conformance Matrix Template

Generators should publish a table like the following, marking each field as full, partial, planned, or — (not applicable / not supported).

Field	Support	Notes
style.naming	full	All five conventions supported.
style.enumStyle	partial	string-union, native only.
features.retries	full
features.pagination	partial	cursor and offset only.
features.reconciliation	full	terraform and kubernetes modes.
features.streaming	planned	Targeted for v0.4.
features.webhooks	—
codegenRules.validation	partial	no-unnamed-operations, required-tags only.

Generator Obligations

Unknown fields — Generators MUST ignore x- extension fields they do not understand. They MUST NOT fail on unknown additionalProperties in a LanguageTarget.

Unknown language targets — Generators MUST skip entries in languages whose language value they do not support. Skipping SHOULD be logged at info level.

Unsupported feature values — If a generator encounters a features.reconciliation mode it does not support, it MUST emit a warning. It MUST NOT silently produce a no-op reconcile function.

Version checking — Generators MUST read the opensdk field and reject files whose major version they do not support with a clear error message.

Versioning Compatibility

Files produced for 1.x.x are guaranteed backward-compatible with any 1.y.y generator where y ≥ x. A generator supporting 1.2.0 MUST correctly process any 1.0.0 or 1.1.0 file.

Major version bumps (e.g. 2.0.0) may remove or rename fields. Generators MUST NOT attempt to process files with an unsupported major version.

Submitting a Conformance Report

Once the conformance test suite is published, generators can submit results at github.com/api-authority/opensdk. Verified generators will be listed in the official registry.