Skip to content

ADR 0008 — OpenCollection native format

Accepted · 2026-01-14

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.

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-types regenerates them and npm run verify:opencollection-types is a CI gate that fails the build if the committed types drift.
  • Protocols map as follows: HTTP, GraphQL (an HTTP item with a graphql body), gRPC, and WebSocket are first-class OpenCollection items. Socket.IO, SSE, and MCP ride along in extensions as x-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.ts convert between the OpenCollection document and Restura’s internal model. An _oc bag 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 extensions field, never inline. The schema’s item, folder, RequestDefaults, and auth objects are additionalProperties: false (and the VS Code extension validates root opencollection.yml against it), so no Restura-only key is added to them.
  • Collection-level extensions keyed by node path. x-restura-sse / x-restura-mcp entries carry a folderPath; x-restura-grpc (schema snapshots deduplicated by sha-256 content hash, plus per-request timeout), x-restura-graphql (user-imported GraphQL schemas as SDL, deduplicated by sha-256 of the SDL; per-request provenance, subscriptionProtocol and the selected operationName on the request entry, in any combination) and x-restura-auth (OAuth1 addParamsToBody, NTLM workstation, WSSE passwordType, with a target of collection/folder/request and the auth type) use path = folder names + item name, matched in document order.
  • Fidelity is tested, not assumed. shared/opencollection/fidelity-roundtrip.test.ts round-trips a fully-populated fixture per request type whose field policy is exhaustive over the type; fields not yet carried (HTTP settings, contractRef, the header secret marker) are listed there as known gaps and documented in docs/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-mqtt lists with a folderPath (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 websocket item (URL, headers, message or message variants). Imported items keep their verbatim _oc bag so OC-only data Restura does not model (a handshake auth block) 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 extension x-restura-websocket (requests: [{ path, index?, … }], like x-restura-http).
  • Socket.IO is a typed item in x-restura-socketio with a folderPath, 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 _oc bag. The older hand-written { key: value } map shape for auth / query still 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-request in their _postman sidecar are rebuilt as native items, and x-restura-socketio entries that an older OpenCollection import kept only in the cached root _oc are 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 _oc bags) 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.

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 _oc preservation 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).