Collection file format

Collections are plain YAML files at the root of your project folder. They are committed to your repository, so the format is a real contract: it is versioned, output is written minimally and in a stable order, and only the fields you actually set are emitted.

This page documents schema v0.8.0, the version shipped in desktop v0.1.0-preview.9.

• formatVersion for a collection is 2.
• formatVersion for a chain is 3 — chains version independently and live in their own files under .tinspec/chains/.

A complete example

formatVersion: 2
name: Example API
requests:
  - name: Get user
    protocol: http
    method: GET
    url: "{{baseUrl}}/users/{{id}}"
    headers:
      Accept: application/json
    auth:
      provider: keycloak-dev
    routeMatcher:
      matcher: edge-kong
      upstream: users-service
      gatewayUrl: "{{gatewayUrl}}"
specSources:
  - name: Users API
    location: http://localhost:8080/openapi.json
routeMatchers:
  - name: edge-kong
    kind: kong
    config: |
      services:
        - name: users-service
          url: http://users:8000
          routes:
            - name: users
              paths: [/api/v1]
              strip_path: true
environments:
  - name: local
    variables:
      baseUrl: http://localhost:8080
      gatewayUrl: https://gw.example.com
      id: "1"

Collection

The complete set of top-level keys.

Key	Type	Required
formatVersion	number	yes
name	string	yes
requests	Request[]	no
environments	Environment[]	no
pipelines	Pipeline[]	no
specSources	SpecSource[]	no
authProviders	AuthProvider[]	no
routeMatchers	RouteMatcher[]	no
defaults	RequestDefaults	no

Note

Chains are not in this file. They are workspace-level, one YAML per chain under .tinspec/chains/ — see Chain.

RequestDefaults

Merged into every request in the collection; a request’s own value wins.

Field	Type	Required
headers	map<string, string>	no
query	map<string, string>	no
variables	map<string, string>	no — layered under the active environment
auth	AuthRef	no — used when a request specifies none

Request

Field	Type	Required	Notes
name	string	yes
protocol	http | grpc | graphql | websocket | langgraph	no	Absent means HTTP
method	GET | HEAD | POST | PUT | PATCH | DELETE | OPTIONS	yes	Required even for gRPC and GraphQL — use POST
url	string	yes	{{var}} allowed; grpc:// or grpcs:// for gRPC
query	map<string, string>	no	Appended at send time; kept out of the URL string
headers	map<string, string>	no	HTTP headers, or gRPC call metadata
body	Body	no
auth	AuthRef	no	A reference by provider name — never an inline credential
grpc	GrpcCall	no	When protocol: grpc
graphql	GraphqlCall	no	When protocol: graphql
langgraph	LangGraphCall	no	When protocol: langgraph
prerunChain	string	no	Name of a chain to run first; its outputs merge into the environment
routeMatcher	RouteMatcherRef	no
useCookieJar	boolean	no	Absent or true means the shared jar applies; false opts out
tests	Assertion[]	no	Evaluated against this request’s own response

Body

Field	Type	Required	Notes
contentType	string	yes	Advisory for multipart — the client sets the real boundary
content	string	yes	Use "" for multipart and file bodies
kind	text | multipart | file	no	Absent means text
parts	BodyPart[]	no	When kind: multipart
filePath	string	no	When kind: file. Workspace-relative inside the project, absolute otherwise; {{var}} allowed

BodyPart

Field	Type	Required	Notes
name	string	yes
kind	text | file	no	Absent means text
value	string	no	Text part; {{var}} allowed
filePath	string	no	File part
contentType	string	no	Default: none for text, application/octet-stream for file
fileName	string	no	Content-Disposition filename; defaults to the path’s basename

Per-protocol calls

GrpcCall

Field	Type	Required	Notes
protoPath	string	no	Workspace-relative .proto or descriptor set
service	string	yes	Fully qualified, e.g. acme.users.v1.UserService
method	string	yes
message	string	no	Request message as JSON; {{var}} allowed
messages	string[]	no	Further messages for client-streaming and bidi, sent in order after message

Streaming mode is not stored — it is read from the descriptor.

GraphqlCall

Field	Type	Required
query	string	yes
variables	string (JSON-encoded object)	no
operationName	string	no

LangGraphCall

Field	Type	Required	Notes
input	string	no	JSON-encoded payload
streamMode	stream | buffered	no	Absent means stream
eventsVersion	string	no
customFields	{ name, path }[]	no	Both required; path is a dot-path into the raw event’s data. A missing path renders blank

Environment

Field	Type	Required
name	string	yes
variables	map<string, string>	no

Secret values never go here.

Assertion

Used by both Request.tests and a chain’s assert node.

Field	Type	Required	Notes
source	status | body | header | var	yes
path	string	no	Dotted JSON path for body, header name for header, variable name for var
op	eq | ne | contains | gt | lt | exists | matches	yes
expected	string	no	Unused for exists; {{var}} allowed

Four sources, seven operators. That is the whole vocabulary at v0.8.0.

Auth

AuthRef

What a request may say about auth. There is no way to express a credential value here.

Field	Type	Required
provider	string	yes — the AuthProvider name
sender	string	no — which sender to authenticate as

AuthProvider

Field	Type	Required	Notes
name	string	yes
kind	script | integration | request	yes
script	string	no	kind: script — workspace-relative path to the JS
integration	keycloak | clerk | auth0 | firebase | supabase	no	kind: integration
request	Request	no	kind: request — any protocol
extract	Extraction (singular)	no	kind: request — the result is exposed as {{token}}
config	map<string, string>	no	Non-secret only: baseUrl, realm, clientId, tokenUrl, scope, domain, grant…
secretRefs	string[]	no	Keychain key names, never values
senders	AuthSender[]	no	Empty means one implicit identity
inject	AuthInject	no	Default when absent: Authorization: Bearer {{token}}

keycloak and auth0 take config.grant of password or client_credentials. firebase and supabase exchange email and password for a token. Generic OAuth2 is not an integration at this version — model it with kind: request or kind: script.

AuthSender

Field	Type	Required	Notes
id	string	yes
label	string	no
tenant	string	no	An informational label only, not a selection axis
secretRef	string	no	This identity’s keychain key name
vars	map<string, string>	no	Non-secret per-sender values, available as {{var}} while resolving the token

AuthInject

Field	Type	Required
target	header | query | cookie	yes
name	string	yes
template	string	yes — e.g. Bearer {{token}}, or bare {{token}}

SpecSource

Field	Type	Required
name	string	yes
location	string	yes — URL or file path to the OpenAPI document
routeMatcher	RouteMatcherRef	no

RouteMatcher

Field	Type	Required	Notes
name	string	yes
kind	kong | nginx | envoy	yes
config	string	yes	The raw gateway config, stored inline
overrides	{ upstream, from, to }[]	no	All three required. from is the backend path, to the gateway-facing one
transcodes	boolean	no	gRPC↔JSON transcoding; auto-detected for Envoy

RouteMatcherRef

Field	Type	Required	Notes
matcher	string	yes
upstream	string	no	Omit to auto-match the spec’s server URL against route upstreams
gatewayUrl	string	no	scheme://host[:port]; {{var}} allowed

Pipeline

The original linear chaining path. It is still in the format, but chains are the chaining surface in the app.

Type	Field	Required
Pipeline	name	yes
	steps	no
PipelineStep	request — a Request name in the same collection	yes
	extract	no

Extraction

Field	Type	Required	Notes
var	string	yes
from	body | header | status	yes
path	string	no	Dotted JSON path for body, header name for header, unused for status

Chain

A separate file — .tinspec/chains/<name>.yaml, formatVersion: 3.

Field	Type	Required
formatVersion	number	yes
name	string	yes
nodes	ChainNode[]	yes
edges	ChainEdge[]	yes

ChainNode

Field	Type	Required	Applies to
id	string	yes	all — edges reference it
type	see below	yes	all
position	{ x, y }, both required	yes	all
request	ChainRequestRef	no	request
extract	Extraction[]	no	request
utility	{ fn, var, args? }	no	generator
rules	{ expr?, port, label? }[]	no	router — ordered, first match wins; an empty expr always matches
config	map<string, string>	no	Per-kind settings
script	string	no	script — async function run(vars, ctx); returned keys become outputs
assertions	Assertion[]	no	assert
fields	{ var, value }[]	no	set
ports	NodePorts	no	all

type is one of the sixteen kinds: request, input, environment, math, transform, generator, set, aggregate, script, assert, condition, router, loop, merge, split, delay.

config keys by kind: input → value; environment → key; math → expr, var; transform → op, expr, var; condition → expr; delay → ms; loop → mode, count, listVar, itemVar, indexVar; aggregate → fromVar, intoVar.

ChainRequestRef is either collection (workspace-relative path) + name, or inline (a whole Request). If both are given, inline wins.

utility.fn is uuid, randomInt (min/max), randomString (length), timestamp (format: unix or iso), sequence (start/step), or list (values, comma-separated).

NodePorts: inputEnabled, outputEnabled (both default true), inputs / outputs as { var, from } mappings (empty means pass everything through), retry, retryDelayMs.

ChainEdge

Field	Type	Required	Notes
id	string	yes
source	string	yes
target	string	yes
sourceHandle	string	no	true/false for a condition, a rule port for a router, body/done for a loop

Diff hygiene

The writer emits only what is set, in a stable order. An empty tests list is dropped rather than written as tests: []; useCookieJar: true is stored as absent because it is the default. A one-header change should be a one-line diff — if it is not, that is a bug worth reporting.