Showing the changes to apps/docs/developer (2 of 30 files). Show all
Unified · Split
| @@ -83,6 +83,8 @@ That is intentional, but the direction is: · 82 unmodified lines | ||
| 83 | 83 | |
| 84 | 84 | The goal is not to erase differences between formats. The goal is to stop those differences from dominating the core architecture. |
| 85 | 85 | |
| 86 | +For the current fidelity tradeoffs and known lossy areas across adapters, see [Import Fidelity](/developer/import-fidelity). | |
| 87 | + | |
| 86 | 88 | ## What a good new adapter should do |
| 87 | 89 | |
| 88 | 90 | A good new adapter should: |
| @@ -0,0 +1,132 @@ | ||
| 1 | +--- | |
| 2 | +title: "Import Fidelity" | |
| 3 | +description: "What executor preserves, normalizes, and currently loses when importing external formats." | |
| 4 | +--- | |
| 5 | + | |
| 6 | +Executor should normalize syntax, not meaning. | |
| 7 | + | |
| 8 | +That means the import pipeline can simplify surface differences between OpenAPI, GraphQL, Google Discovery, and MCP, but it should not silently erase semantics that change execution, trust, or user understanding. | |
| 9 | + | |
| 10 | +The practical shape is: | |
| 11 | + | |
| 12 | +- keep the raw source document or manifest | |
| 13 | +- keep adapter-native metadata that does not fit the common model cleanly | |
| 14 | +- promote execution-relevant semantics into first-class IR | |
| 15 | + | |
| 16 | +## The fidelity buckets | |
| 17 | + | |
| 18 | +This audit uses four buckets: | |
| 19 | + | |
| 20 | +- `Raw source`: the original imported document or manifest | |
| 21 | +- `Adapter/native`: typed provider data or native blobs attached during import | |
| 22 | +- `IR`: first-class catalog symbols and capability metadata | |
| 23 | +- `UI today`: what current inspection surfaces directly | |
| 24 | + | |
| 25 | +Current inspection is still narrow. It mostly shows projected schemas plus `tool.executable.native[0]`, not all preserved native blobs or capability-native metadata. | |
| 26 | + | |
| 27 | +## OpenAPI | |
| 28 | + | |
| 29 | +| Source detail | Raw source | Adapter/native | IR | UI today | Notes | | |
| 30 | +| --- | --- | --- | --- | --- | --- | | |
| 31 | +| Operation auth requirements and security schemes | Yes | No | No | No | Operation `security` is not promoted; imported capabilities currently use `auth: none`. | | |
| 32 | +| Exact response variants, status codes, and headers | Yes | Partial | No | Partial | Import chooses one preferred response, then projects one synthetic `2XX` response set. | | |
| 33 | +| Parameter serialization (`style`, `explode`, `allowReserved`, content-based params) | Yes | Mostly no | No | No | The IR can model these, but the OpenAPI importer currently only takes parameter `schema`. | | |
| 34 | +| Multiple request and response media types | Yes | Partial | Partial | Partial | Import picks a preferred content entry for typing; response docs keep content types only for the chosen response. | | |
| 35 | +| `servers` defaults | Yes | No | No | No | The IR can represent scope server defaults, but OpenAPI import does not populate them. | | |
| 36 | +| Rich schema semantics beyond the importer subset | Yes | Partial | Partial | Partial | Unsupported JSON Schema shapes fall back to `unknown` plus native preservation. | | |
| 37 | + | |
| 38 | +## GraphQL | |
| 39 | + | |
| 40 | +| Source detail | Raw source | Adapter/native | IR | UI today | Notes | | |
| 41 | +| --- | --- | --- | --- | --- | --- | | |
| 42 | +| Subscription root fields as tools | Yes | Partial | No | No | The manifest records `subscriptionTypeName`, but tool generation only materializes query and mutation fields. | | |
| 43 | +| Full field result shapes for generated field tools | Yes | Partial | Partial | Partial | Field-tool outputs are heuristic projections, not full result types. | | |
| 44 | +| Union and deep nested selections | Yes | Partial | Partial | Partial | Unions degrade to `__typename`; nested selection stops after depth 2 in generated field tools. | | |
| 45 | +| Arbitrary caller-selected field projections | Yes | Partial | No | No | Generated field tools are compiled with fixed selections; the raw `request` tool is the escape hatch. | | |
| 46 | +| Deprecation reasons | Yes | Partial | Partial | No | GraphQL schemas emit `deprecated: true` plus `x-deprecationReason`, but the generic schema importer only keeps `deprecated` as first-class shape metadata. | | |
| 47 | + | |
| 48 | +GraphQL is a special case: the main loss is not the raw source being discarded, but the generated field-tool projection being intentionally narrower than the schema. That tradeoff is reasonable for discoverability, but only if the system continues to preserve and expose the raw request path. | |
| 49 | + | |
| 50 | +## Google Discovery | |
| 51 | + | |
| 52 | +| Source detail | Raw source | Adapter/native | IR | UI today | Notes | | |
| 53 | +| --- | --- | --- | --- | --- | --- | | |
| 54 | +| OAuth scope descriptions | Yes | Partial | No | No | Document-level scope descriptions are extracted, but the IR security scheme rewrites scopes to `{ scope: scope }`. | | |
| 55 | +| Rich media upload metadata | Yes | Partial | Partial | Partial | Upload support is collapsed to booleans such as `supportsMediaUpload` and `supportsMediaDownload`. | | |
| 56 | +| Service-level metadata (`title`, `description`, `batchPath`, `documentationLink`) | Yes | Partial | No | No | The extracted manifest has these fields, but per-operation provider data does not carry them into the catalog. | | |
| 57 | +| Parameter descriptions, repeated-ness, enums, defaults | Yes | Yes | Mostly yes | Mostly yes | This area is comparatively good. | | |
| 58 | +| Request and response schemas | Yes | Yes | Yes | Yes | Core schema structure is preserved reasonably well. | | |
| 59 | + | |
| 60 | +Google Discovery is less lossy than OpenAPI on request and response typing, but it still loses useful service metadata and the human meaning attached to OAuth scopes. | |
| 61 | + | |
| 62 | +## MCP | |
| 63 | + | |
| 64 | +| Source detail | Raw source | Adapter/native | IR | UI today | Notes | | |
| 65 | +| --- | --- | --- | --- | --- | --- | | |
| 66 | +| Non-tool MCP resources such as prompts or resources | No | No | No | No | The adapter only discovers `listTools()`. Anything outside the tool list never enters import. | | |
| 67 | +| Extra tool metadata beyond `name`, `description`, `inputSchema` or `parameters`, and `outputSchema` | Partial | Partial | No | No | The manifest schema keeps only a narrow subset of listed tool fields. | | |
| 68 | +| Tool-level safety or effect hints, if present | Partial | No | No | No | Imported MCP operations are currently hardcoded to `effect: action`. | | |
| 69 | +| Tool input and output schemas | Yes | Yes | Yes | Yes | This is the strongest part of the current MCP import. | | |
| 70 | +| Server-level metadata outside the tool list | No | No | No | No | The stored MCP "document" is a synthesized tool manifest, not a richer upstream server description. | | |
| 71 | + | |
| 72 | +MCP is the most structurally lossy adapter today because the discovery step itself only imports tools and already narrows their metadata aggressively. | |
| 73 | + | |
| 74 | +## Cross-cutting UI caveat | |
| 75 | + | |
| 76 | +Even when data is preserved natively, the current inspection UI often does not show it directly. | |
| 77 | + | |
| 78 | +Today inspection primarily exposes: | |
| 79 | + | |
| 80 | +- projected call and result schemas | |
| 81 | +- capability summary text | |
| 82 | +- the first executable native blob | |
| 83 | + | |
| 84 | +That means "preserved in native data" and "visible to a user" are still different states. | |
| 85 | + | |
| 86 | +## What should be first-class in IR | |
| 87 | + | |
| 88 | +These semantics are worth promoting into the common model because they affect execution or trust: | |
| 89 | + | |
| 90 | +- auth and security requirements described by the source format | |
| 91 | +- response and status variants | |
| 92 | +- HTTP parameter serialization | |
| 93 | +- upload, download, and streaming traits | |
| 94 | +- GraphQL selection and subscription semantics | |
| 95 | +- source-provided safety or idempotency hints | |
| 96 | + | |
| 97 | +By contrast, many provider-specific labels, service metadata fields, and raw source extras are fine to keep in adapter-native metadata as long as they remain inspectable. | |
| 98 | + | |
| 99 | +## Recommended priority order | |
| 100 | + | |
| 101 | +### P0 | |
| 102 | + | |
| 103 | +- OpenAPI auth and security requirements | |
| 104 | +- OpenAPI response variants and status distinctions | |
| 105 | +- Google Discovery scope descriptions | |
| 106 | +- MCP discovery breadth: decide whether executor intends to import only tools or broader MCP surface area | |
| 107 | + | |
| 108 | +### P1 | |
| 109 | + | |
| 110 | +- OpenAPI parameter serialization | |
| 111 | +- GraphQL subscription modeling | |
| 112 | +- GraphQL field-tool projection metadata so the fixed-selection behavior is explicit | |
| 113 | +- Google Discovery service metadata surfacing | |
| 114 | +- MCP tool metadata preservation beyond the current narrow manifest | |
| 115 | + | |
| 116 | +### P2 | |
| 117 | + | |
| 118 | +- Better UI fallback to native/provider metadata | |
| 119 | +- Richer diagnostics for intentionally lossy normalization | |
| 120 | +- A fixture-backed audit matrix test per adapter | |
| 121 | + | |
| 122 | +## The IR boundary | |
| 123 | + | |
| 124 | +The right boundary is: | |
| 125 | + | |
| 126 | +- `raw source` remains the source of truth | |
| 127 | +- `adapter-native metadata` keeps source-specific details close to their format | |
| 128 | +- `IR` stays unified, but it must be lossless for downstream semantics | |
| 129 | + | |
| 130 | +If executor keeps that line clear, a standardized representation is a strength. | |
| 131 | + | |
| 132 | +If executor lets semantically important details live only in hidden native blobs, the standardized representation becomes misleading. | |