ADR 0008 — OpenCollection native format
Context
Section titled “Context”Every API client locks you into its own format. Postman’s is locked, Insomnia’s is locked, Bruno’s is its own dialect. Switching tools means a lossy migration each time, which is a real reason teams stay on tools they’ve outgrown. Restura needs a canonical on-disk representation for collections that survives round-trips, is vendor-neutral so users can leave, and covers the request-shaped protocols Restura supports — not just HTTP. We also need the in-memory TypeScript types to stay in lock-step with the schema; hand-maintaining types alongside a JSON Schema drifts immediately.
Decision
Section titled “Decision”Adopt OpenCollection as Restura’s native read/write format, implemented in shared/opencollection/. Two on-disk layouts are supported: a single bundled YAML document and a directory layout through the Node fs adapters.
- The spec’s TypeScript types (
spec-types.ts) are generated from the vendored JSON Schema, not hand-written.npm run gen:opencollection-typesregenerates them andnpm run verify:opencollection-typesis a CI gate that fails the build if the committed types drift. - Protocols map as follows: HTTP, GraphQL (an HTTP item with a
graphqlbody), gRPC, and WebSocket are first-class OpenCollection items. Socket.IO, SSE, and MCP ride along inextensionsasx-restura-socketio/x-restura-sse/x-restura-mcp, preserved across import/export (see the amendment below). (WebSocket and Socket.IO: see the 2026-10-30 amendment — both are now typed collection items.) - Connection-based protocols (Kafka, MQTT) have no per-request shape, so they are deliberately not represented in a collection. (Superseded by the 2026-10-18 amendment: they are saved as connection presets.)
to-internal.ts/from-internal.tsconvert between the OpenCollection document and Restura’s internal model. An_ocbag preserves original fields the internal model can’t represent, so an unedited imported item re-exports verbatim even for features Restura doesn’t surface in its UI.
Amendment (2026-10-12): vendor-extension shape
Section titled “Amendment (2026-10-12): vendor-extension shape”The original wording above overstated the result: through 2026-10 SSE/MCP fields, foldered SSE/MCP placement, and OAuth1/NTLM/WSSE auth were dropped on round-trip (#863, #866, #869, #975). The fidelity fixes settle how Restura stores what the schema can’t hold:
- Everything Restura-specific lives in the root
extensionsfield, never inline. The schema’s item, folder,RequestDefaults, and auth objects areadditionalProperties: false(and the VS Code extension validates rootopencollection.ymlagainst it), so no Restura-only key is added to them. - Collection-level extensions keyed by node path.
x-restura-sse/x-restura-mcpentries carry afolderPath;x-restura-grpc(schema snapshots deduplicated by sha-256 content hash, plus per-requesttimeout),x-restura-graphql(user-imported GraphQL schemas as SDL, deduplicated by sha-256 of the SDL; per-request provenance,subscriptionProtocoland the selectedoperationNameon the request entry, in any combination) andx-restura-auth(OAuth1addParamsToBody, NTLMworkstation, WSSEpasswordType, with atargetof collection/folder/request and the authtype) usepath= folder names + item name, matched in document order. - Fidelity is tested, not assumed.
shared/opencollection/fidelity-roundtrip.test.tsround-trips a fully-populated fixture per request type whose field policy is exhaustive over the type; fields not yet carried (HTTPsettings,contractRef, the headersecretmarker) are listed there as known gaps and documented indocs/opencollection.md.
Amendment (2026-10-13): x-restura-http and partial request settings
Section titled “Amendment (2026-10-13): x-restura-http and partial request settings”The per-request HTTP version preference (#864, desktop-only) has no slot in the schema’s http.settings, so it is carried in a new collection-level extension, x-restura-http (requests: [{ path, httpVersion }], matched by name path like x-restura-grpc; auto is not emitted). It is the one HTTP setting that now round-trips; the rest of settings stays a known gap.
Import applies only httpVersion. HttpRequest.settings became a partial override (RequestSettingsOverride) resolved field by field against the workspace defaults, so importing a version preference no longer pins timeout, redirect, and TLS-verification values on the request. Unknown or malformed entries are ignored and the request stays on auto.
Amendment (2026-10-18): Kafka / MQTT connection presets
Section titled “Amendment (2026-10-18): Kafka / MQTT connection presets”Superseding the “Kafka, MQTT … not represented” bullet above (#984): a Kafka or MQTT tab can be saved as a connection preset — the broker connection plus the operation drafts (Kafka produce/consume, MQTT publish/subscribe and saved publishes). Internally they are KafkaRequest / MqttRequest (shared/types/broker.ts), members of CollectionRequest but not of the tab Request union: opening one seeds a connection-mode tab instead of becoming a tab request.
- Extensions, same shape as SSE/MCP. Presets ride in root
x-restura-kafka/x-restura-mqttlists with afolderPath(shared/opencollection/broker-items.ts); they are covered by the fidelity harness and validate against the strict schema. - No secret material in the preset. The preset types have no password/token/passphrase fields at all, the Zod schemas strip any that ride along, and the exporters pick fields explicitly. Credentials are copied into the desktop secure store under a preset-scoped key (
kafka:preset-<requestId>:<field>,mqtt:…) and copied back onto the tab connection when the preset is opened, so they never reach collection persistence, OpenCollection exports or git-native files. A different machine — or a re-import, which mints new ids — re-enters them. {{var}}resolves at send time (brokers / broker URL at connect, topics at subscribe, topic/key/payload/headers at send); presets store values unresolved.- Postman / Insomnia / Bruno exports emit a named non-runnable stub with a warning; the CLI skips presets with a notice.
Amendment (2026-10-30): WebSocket / Socket.IO collection items
Section titled “Amendment (2026-10-30): WebSocket / Socket.IO collection items”#1209 gives WebSocket and Socket.IO saved collection items, following the Kafka / MQTT preset pattern: WebSocketRequest / SocketIoRequest (shared/types/stream-preset.ts) are members of CollectionRequest but not of the tab Request union. Opening one seeds a connection-mode tab, and the collection runner and the CLI skip them with a reason.
- WebSocket is a native typed item. It is written as the schema’s own
websocketitem (URL, headers, message or message variants). Imported items keep their verbatim_ocbag so OC-only data Restura does not model (a handshakeauthblock) survives an unedited round trip. Restura-only fields (subprotocols, reconnect / heartbeat / permessage-deflate options, frame assertion, the composer draft when saved messages exist) ride in the path-keyed root extensionx-restura-websocket(requests: [{ path, index?, … }], likex-restura-http). - Socket.IO is a typed item in
x-restura-socketiowith afolderPath, the same shape as Kafka / MQTT. It is no longer an opaque ride-along: the list is rebuilt from the live tree on export and imported entries keep no_ocbag. The older hand-written{ key: value }map shape forauth/querystill imports and is written back in the row form, so such files are not byte-stable on their first re-export. - Persisted collections migrate (store persist v3 → v4). Postman v3 placeholder folders that hold a
websocket-request/socket.io-requestin their_postmansidecar are rebuilt as native items, andx-restura-socketioentries that an older OpenCollection import kept only in the cached root_ocare materialised as native Socket.IO items, so the next export does not drop them. The migration is per-collection and fail-safe: a collection that cannot be upgraded is kept unchanged. - Secrets. Header, query and handshake-auth rows are stored as typed, like the live connection stores (not keychain handles). Export redaction blanks credential-named rows, URL credentials (userinfo and credential-named query values, including URLs inside cached
_ocbags) and every literal handshake-auth value. Message payloads and subprotocols are not redacted, the same as HTTP bodies. - Accepted limitation. OpenCollection-imported
<name> (WebSocket)placeholder folders from before #1209, and file-backed (git-native) collections that hold Postman placeholders, are not auto-upgraded. They still round-trip losslessly through their bag; re-import the file to get native items.
Consequences
Section titled “Consequences”Positive
- Users can move in and out of Restura with a tested round-trip (known gaps are listed in the user guide); the same files drive the desktop app, the web app, and
restura-cli. - The codegen gate guarantees the runtime types never silently diverge from the published schema.
- Vendor extensions give Restura room to represent its own protocols without forking the spec.
Negative
- Two layouts (bundled + directory) double the reader/writer surface and its tests.
- The
_ocpreservation bag adds complexity to the converters — the price of byte-stable round-trips. - Kafka/MQTT presets carry no credentials, so a shared preset needs its password/token re-entered on each machine (and after a re-import).
Related
Section titled “Related”- Source:
docs/adr/0008-opencollection-native-format.md - User guide: OpenCollection.
- Related: ADR 0005, ADR 0007.
- CI gate: Contract tests & CI — the
verify:opencollection-typesdrift check.