references/codegen-interpretation.md

# OpenAPI and SDK/codegen interpretation

This guide applies to the pinned `ycloud-api-v2.yaml` snapshot and the
generated domain references. It explains where generated model shape must not
be mistaken for API behavior. The snapshot is a derived, checked-in intake
artifact for this Plugin release; it does not replace the upstream API Owner's
canonical source.

## Contract hierarchy and provenance

Use the exact OpenAPI path, method, operationId, parameter, schema, and
description as the raw HTTP contract. The generated domain reference is a
scoped index of that contract, and Skill workflow text is subordinate to both.
If these layers disagree, stop and report contract drift instead of silently
choosing one.

The effective pinned snapshot is OpenAPI `3.0.0`, API `info.version` `v2`, with SHA-256
`8592bd4cc37186655a480dd86ce6bac6731543727327a2871d9103a0b8ed9e81` (438485
bytes, 10750 lines after the correction below). `scripts/normalize_openapi_source.py` produces
the deterministic normalized JSON used by the reference generator. A future
source refresh must replace the snapshot and regenerate every domain reference
before drift, validator, and test gates are run.

Snapshot release provenance:

- Snapshot date: `2026-08-20`.
- Release scope: pinned for the Source Governance MVP and six-domain Skill suite.
- Public contract authority: `https://docs.ycloud.com/reference`.
- Upstream path: `apis/ycloud-api-v2.yaml`.
- Upstream commit: `5ba1b652e00d27b1a3c097f012cff2da93df624c`.
- Unmodified upstream SHA-256:
  `080746758babdad4689efb35a6b7c24108b33afb527a80bb8e82d462ca8267ed`
  (438478 bytes, 10750 lines).
- Ownership boundary: the upstream YCloud API owner remains authoritative;
  this repository owns only the pinned Plugin release artifact and its derived
  references. Machine-readable provenance is recorded in
  `release-metadata.json`.

The local `template-name-underscores` correction changes exactly seven
`pattern: '[a-z0-9]{1,512}'` occurrences to
`pattern: '[a-z0-9_]{1,512}'`. The current REST service permits underscores
(`TEMPLATE_NAME_PATTERN = [_a-z0-9]{1,512}`), as do the snapshot's own example
names. This correction is part of the Plugin intake, not a claim that the
pinned upstream commit already contains it. The source revision and relative
service file are recorded in the correction's evidence.

Release metadata schema version 2 separates `canonicalSourceSha256` from the
effective `snapshotSha256` and records ordered `snapshotCorrections`, including
exact original/replacement text, occurrence counts, reasons, and evidence.
`scripts/validate_plugin.py` and the capability manifest generator undo these
corrections, verify the unmodified source hash, and replay them to reproduce
the packaged snapshot. The check uses only packaged data and requires no
network or upstream checkout; it verifies the recorded intake, not the remote
Git commit itself. A future unmodified intake must use an empty correction
array and identical source/snapshot hashes. Refreshes with local corrections
must update the record and pass the same reproducibility check.

## Schema composition

- `allOf` is OpenAPI schema composition. Preserve every component and its
  constraints when explaining a request or response.
- A generated SDK may represent `allOf` as class inheritance, a flattened
  model, or a composition type. That representation is a codegen hint, not an
  additional API guarantee.
- `oneOf`, `anyOf`, discriminator fields, required properties, enum values,
  formats, and numeric/string bounds retain their contract meaning. Do not
  replace them with a guessed SDK hierarchy.

## Extensions and generated names

`x-group-parameters`, `x-enum-varnames`, and `x-enum-descriptions` are metadata
for documentation or code generators. They do not create server behavior,
change requiredness, or establish a runtime enum guarantee beyond the schema
itself. Model/class/property names generated by a tool are likewise not stable
SDK API names.

`operationId` is an OpenAPI operation identifier only. Never turn
`whatsapp_message-send`, `whatsapp_media-upload`, or another operationId into a
Java, TypeScript, Python, Go, or PHP method name unless the project contains a
confirmed SDK artifact, version, and reliable method documentation.

## Description-only rules

OpenAPI permits constraints to appear in prose rather than as JSON Schema
keywords. Keep those descriptions visible when constructing examples:

- `WhatsappMessageSendRequest` requires `from` and `type`, and its prose says
  to provide exactly one of `to` or `recipient`; when both are provided, `to`
  takes precedence and `recipient` is ignored.
- The flat message request uses several optional payload fields. The selected
  `type` determines which payload is required (`template`, `text`, `image`,
  `video`, `audio`, `document`, `sticker`, `location`, `interactive`,
  `contacts`, or `reaction`). This is a description-level semantic rule; the
  absence of `oneOf`/a discriminator is a codegen-compatible shape, not
  permission to send all optional fields together.
- Direct and queued message operations have different submission semantics,
  and fields such as `filterUnsubscribed`/`filterBlocked` are endpoint-specific
  as stated in their descriptions.
- Template and webhook request descriptions contain lifecycle and conditional
  behavior that must remain in derived references even when a schema resolver
  only follows `$ref`.

## `$ref` sibling descriptions

OpenAPI 3.0 tooling may ignore sibling keys next to `$ref`. For example,
message payload properties carry a `$ref` plus a description such as “Required
when `type` is `text`.” The reference generator explicitly prints these
descriptions and property-level constraints; a consumer must not discard them
just because a generated model only exposes the referenced type.

## Unknowns and safety boundaries

The source does not establish an error taxonomy, retry policy, `Retry-After`,
rate limits, idempotency behavior, delivery guarantees, or webhook signature
header/algorithm/canonicalization unless a specific operation description says
so. Missing declarations mean “not confirmed,” not “impossible.” Use raw HTTP
contract examples with synthetic identifiers and placeholders such as
`<YCLOUD_API_KEY>` until project facts or reliable upstream SDK documentation
confirm anything more specific.