Workspace file format
The folders and JSON documents that store a workspace.
Overview
Every Relay workspace is a folder of JSON documents, one file for each workspace, environment, collection, folder and request. A workspace you keep in a folder of your own, such as a directory in a Git repository, uses this format, and so does a workspace stored inside Relay. The format is designed to be read, reviewed and merged like source code: the same workspace always produces the same bytes, and changing one request rewrites only that request's file.
To move a workspace into a folder, see Storing a workspace in a folder.
Folder layout
relay-workspace.json
environments/
staging.json
production.json
collections/
orders/
collection.json
create-order.json
list-orders.json
refunds/
folder.json
create-refund.jsonrelay-workspace.json: The workspace itself. Its presence marks the folder as a Relay workspace.environments/<slug>.json: One file for each environment.collections/<slug>/collection.json: One directory for each collection, holding the collection's own document.<slug>.jsoninside a collection or folder directory: One file for each request.<slug>/folder.jsoninside a collection or folder directory: One directory for each folder, holding the folder's own document. Folders nest to any depth.
The directory a document is in decides its parent. No document lists its children, so you can move a request to another folder by moving its file.
Relay reads only relay-workspace.json and the .json files under environments/ and collections/. It ignores hidden files and files that don't end in .json, and it writes nothing else to the folder, so a README or a .gitignore can live beside the documents.
File names
Relay names each file and directory with a slug of the item's name: lowercase ASCII letters and digits, with every run of other characters turned into one hyphen, up to 64 characters. "List Refunds" becomes list-refunds.json, and "Café Orders" becomes cafe-orders.
- When two siblings would get the same slug, ignoring case, the later one gets a suffix:
list-refunds-2.json,list-refunds-3.json. - A request's file is never named
collection.jsonorfolder.json, so a request called "Folder" becomesfolder-2.json. - A file keeps its name until you rename the item in Relay. If you rename a file by hand, Relay keeps the new name. The name Relay shows is the
nameinside the document, not the file name.
Ids and order
Every document has an id, a UUID that must be unique across the workspace. Relay uses ids, not file names, to keep track of items, so a copied file needs a new id.
Every document except relay-workspace.json has an order, an integer that sorts it among its siblings. Folders and requests in the same directory are numbered together. Items without an order sort last, and items with the same order sort by name and then by id. When you move one item in Relay, Relay keeps the other items' numbers where it can, so a move usually rewrites only the file you moved.
Formatting
Relay writes every document the same way:
- Pretty-printed with two-space indentation and keys sorted alphabetically.
- Slashes in strings aren't escaped.
- Dates are ISO 8601.
- The file ends with a newline.
Empty values are left out. A request without scripts has no scripts key, a collection that inherits its auth has no auth key, and a row is written with enabled only when it's turned off and with description only when it has one.
What isn't written
The files hold nothing that's specific to your Mac or that would change without an edit:
- Secrets: A secret variable is written with its
keyand"secret": true, and without its value. Auth credentials such as tokens and passwords are written empty, unless the whole value is variable references such as{{token}}or{{user}}:{{password}}. Client certificates aren't written at all. Relay keeps these values in its own storage on your Mac. - Row ids: Header, parameter and variable rows have no ids in the files.
- Request bookkeeping: Requests don't record their workspace or when they were created and changed.
- Local state: The active environment, drafts, history, cookies and OAuth 2.0 tokens live in Relay's own storage, not in the folder.
For more about secrets, see Keeping secrets on your Mac.
Workspace document
relay-workspace.json has these keys:
Prop
Type
{
"auth" : {
"auth" : {
"bearer" : {
"token" : "{{accessToken}}"
}
},
"mode" : "Custom"
},
"formatVersion" : 1,
"id" : "7D1E6C2A-4F0B-4C55-9A57-3B8E2F1D9C40",
"name" : "Orders API",
"settings" : {
"timeout" : 60
},
"variables" : [
{
"key" : "baseUrl",
"value" : "https://api.example.com/v2"
},
{
"key" : "apiKey",
"secret" : true
}
]
}Environment document
Each file in environments/ has id, order, name and variables.
{
"id" : "C3A9F0E2-1B7D-4E8A-8F21-6D5C0B9A7E13",
"name" : "Staging",
"order" : 1,
"variables" : [
{
"key" : "baseUrl",
"value" : "https://staging.api.example.com/v2"
},
{
"description" : "Issued by the staging identity provider",
"key" : "accessToken",
"secret" : true
},
{
"enabled" : false,
"key" : "debug",
"value" : "true"
}
]
}Each row of variables, and of a request's headers and queryParams, has these keys:
Prop
Type
Collection and folder documents
collection.json and folder.json have id, order, name, and when they're set, variables, auth, scripts and settings. A collection.json can also have colorName and iconName, the color and icon the sidebar shows for the collection.
{
"auth" : {
"mode" : "No Auth"
},
"id" : "E8F14A3B-2C6D-4B9E-A0F7-5D1C3B8A9E26",
"name" : "Refunds",
"order" : 0
}Request document
A request's file has these keys:
Prop
Type
{
"body" : {
"json" : {
"_0" : "{\n \"sku\": \"{{sku}}\",\n \"quantity\": 2\n}"
}
},
"documentation" : {
"operationId" : "createOrder",
"summary" : "Create an order",
"tags" : [
"orders"
]
},
"headers" : [
{
"key" : "Accept",
"value" : "application/json"
},
{
"key" : "Idempotency-Key",
"value" : "{{$guid}}"
}
],
"id" : "5B2C8E41-9D3A-4F67-B0E8-1A4C7D2F6E95",
"method" : "POST",
"name" : "Create Order",
"order" : 2,
"queryParams" : [
{
"description" : "Skip the confirmation email",
"enabled" : false,
"key" : "notify",
"value" : "false"
}
],
"scripts" : {
"postResponse" : "test(\"returns 201\", () => {\n expect(res.status).toBe(201);\n});"
},
"settings" : {
"followsRedirects" : false
},
"url" : "{{baseUrl}}/orders"
}Bodies
body is an object with one key, the body type:
| Body | JSON |
|---|---|
| None | {"none": {}} |
| JSON | {"json": {"_0": "<text>"}} |
| Text | {"raw": {"_0": "<text>", "contentType": "text/plain"}} |
| Form URL-Encoded | {"formURLEncoded": {"_0": [<rows>]}} |
| Multipart Form | {"multipartFormData": {"_0": [<parts>]}} |
| GraphQL | {"graphQL": {"_0": {"query": "…", "variables": "…", "operationName": "…"}}} |
Auth
auth is an object with a mode:
| Auth | JSON |
|---|---|
| Inherit from parent | {"mode": "Inherit"} |
| No Auth | {"mode": "No Auth"} |
| Bearer Token | {"mode": "Custom", "auth": {"bearer": {"token": "…"}}} |
| Basic Auth | {"mode": "Custom", "auth": {"basic": {"username": "…", "password": "…"}}} |
| Other types | {"mode": "Custom", "auth": {"<type>": {…}}} |
The other types are apiKey, jwt, oauth2, oauth1, digest, ntlm, awsSigV4 and hawk. A request, folder or collection that inherits its auth leaves auth out, and one without auth inherits.
Settings
settings holds only the fields that are set: timeout (seconds), followsRedirects, maximumRedirects, followsOriginalMethod, keepsAuthorizationAcrossOrigins, verifiesCertificates and usesProxy. A field that's left out inherits its value from the level above.
Invalid files
When a file can't be read, because it isn't valid JSON, has merge conflict markers, is missing its id or repeats another document's id, or when a collection or folder directory has no collection.json or folder.json, Relay opens the workspace read-only and lists the files to fix. A workspace whose relay-workspace.json is missing, can't be read or has a newer formatVersion can't be opened. For details, see Resolving workspace file issues.
See Also
- Storing a workspace in a folder: Keep a workspace as files in a folder you choose and share it with Git.
- Keeping secrets on your Mac: Keep tokens and passwords out of shared workspace files.
- Resolving workspace file issues: Fix a workspace that's read-only or can't be found because of problems with its files.