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.json
  • relay-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>.json inside a collection or folder directory: One file for each request.
  • <slug>/folder.json inside 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.json or folder.json, so a request called "Folder" becomes folder-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 name inside 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 key and "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:

BodyJSON
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:

AuthJSON
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