Schema bundles and conversion warnings
Understand ApiFuse developer schema bundle identity, hashes, target artifacts, and warning semantics.
Schema bundles and conversion warnings
A schema bundle is the canonical developer artifact for one visible provider operation. Gateway MCP developer tools, OpenAPI docs, and generated typed snippets all reference the same bundle identity so coding agents can detect drift.
Bundle fields
| Field | Meaning |
|---|---|
artifactVersion | Version of the developer artifact envelope contract. |
registryVersion | Provider-registry projection version used to build the bundle. |
providerHash | Hash of the canonical provider bundle. |
operationHash | Hash of operation metadata excluding full target code artifacts. |
schemaHash | Hash of normalized input/output JSON Schemas. |
targetArtifactHash | Hash for each generated target artifact. |
bundleHash | Hash covering the operation bundle, target hashes, and conversion warnings. |
catalogHash | Hash of the visibility-filtered catalog index. |
Hash parity
The same visible operation returned by apifuse_dev_get_operation_spec and apifuse_dev_get_schema_bundle must report the same artifactVersion, schemaHash, and bundleHash.
Gateway MCP artifact access
Developer artifacts are exposed to coding agents through Gateway MCP tools, not Landing-owned public API routes:
| Tool | Description |
|---|---|
apifuse_dev_list_providers | Visibility-filtered catalog index. |
apifuse_dev_get_operation_spec | One operation contract without inlining generated target payloads. |
apifuse_dev_get_schema_bundle | Operation schema bundle with selected JSON Schema, OpenAPI, TypeScript, Zod, or Pydantic targets. |
Successful schema bundle responses include artifactVersion, schemaHash, bundleHash, and target artifact hashes.
No request-path conversion
Target artifacts are generated at build time. Gateway MCP serves generated files or visibility-filtered slices of generated files; it does not run TypeScript, Zod, or Pydantic conversion on the request path.
Conversion warnings
Some JSON Schema constructs cannot be represented exactly in every target language. ApiFuse handles those cases in one of two ways:
- strict generation fails before publishing unsafe artifacts; or
- the target artifact is published with an explicit conversion warning.
Warnings are part of the schema bundle and are covered by the bundle hash. Treat a new warning as a contract change and review generated validation behavior before shipping application code.
Example warning shape:
{
"target": "pydantic",
"code": "lossy_union_discriminator",
"message": "The JSON Schema union could not be represented with an exact Pydantic discriminator.",
"path": ["output", "items"]
}Public visibility and safe errors
Public artifacts are default-deny. Hidden providers and operations must be indistinguishable from missing resources in public responses. Error bodies, counts, hashes, ETags, cache keys, and support diagnostics must not reveal hidden provider identifiers or internal classification.