This document defines the language-neutral contract that the Codeful SDK generator and generated connector SDKs must preserve. It applies to every language target. Language-specific naming and idioms remain governed by that language's Azure SDK guidelines.
The connector Swagger document is the backend contract. A generated client may offer an idiomatic API surface, but it must always produce requests whose JSON property names, primitive and collection shapes, required properties, and referenced schemas comply with the Swagger operation definition.
There is no language-specific choice in the request wire format. If two SDKs
serialize different payloads for the same Swagger operation, at least one SDK is
incorrect. For string/binary Swagger request bodies, the wire contract is raw
bytes with the declared content type, such as application/octet-stream, rather
than a JSON object.
Non-deprecated, non-internal, non-trigger operations are callable SDK methods. Their request and response models are generated from the operation definition and use the operation's declared HTTP method, path, parameters, and schemas.
The generator may exclude a route only through an explicit, documented policy, such as unsupported multipart transport or a curated replacement route. Such a policy must preserve the intended SDK contract and be validated against the Swagger input.
Routes marked x-ms-trigger are not ordinary data-plane invocations. They are
registered with the Connector Namespace service as trigger configurations. The
Connector Namespace monitors the connector and POSTs a callback payload to the
application's registered endpoint when the trigger fires.
Generated SDKs provide trigger operation identifiers, parameter metadata, and typed callback payloads where the trigger response has a JSON model. They do not expose a trigger route as a normal action method solely because it has an HTTP verb in Swagger. See Connector Triggers and the trigger-registration skill for the registration and callback flow.
Routes marked x-ms-visibility: internal are discovery helpers, not ordinary
connector actions. The generator may retain them when a public operation's
dynamic values or dynamic schema metadata references their operation ID. In that
case, the generated SDK may expose an explicitly marked callable discovery API
so infrastructure consumers, such as the SDK LSP, can enumerate dynamic values
or schemas. It must remain distinct from customer-facing action methods and must
not be presented as a normal connector operation.
Generated operation, model, and parameter names are deterministic transformations of the connector definition and generator policy. They are not selected by heuristics at runtime. Any rename or route substitution must be implemented in the generator as an explicit, tested rule so every language target can apply the same contract decision.
Generated-client validation must use a pinned Swagger snapshot and pinned generator revision. Live ARM Swagger is useful for refreshes but is not a stable byte-for-byte test input because descriptions and metadata can change outside a pull request.
For each generated connector and language target, validation must confirm:
- Callable actions match the intended non-trigger Swagger operations after documented route-selection policy is applied.
- Trigger operations are represented as registration and callback contracts, not ordinary invocations.
- Internal discovery operations remain non-public unless explicitly required by a documented SDK metadata mechanism.
- Outbound JSON keys and values match the Swagger request schema exactly.
- Inbound JSON binds to the corresponding Swagger response or trigger schema.
Cross-language validation should emit a deterministic report for each connector that records the pinned Swagger input, generator revision, public operation surface, and request/response wire-contract comparison.