Skip to main content

Rostyman Workspace Format

The .rostyman-workspace format bundles an entire workspace into one JSON file: multiple collections plus workspace-level assets — mock servers, workflows, scheduled jobs, global variables, vault secrets, browser tests, and database connections.

It is an open, documented format; any tool may read or write it. Each collection inside a workspace is a complete Rostyman Collection document, so a workspace is essentially "many collections + extras."

Overview​

PropertyValue
File extension.rostyman-workspace
MIME typeapplication/json
EncodingUTF-8
Version1.0

Top-Level Structure​

{
  "_type": "rostyman_workspace",
  "_version": "1.0",
  "info": {
    "name": "My Workspace",
    "description": "Optional",
    "exportedAt": "2026-06-06T12:00:00.000Z",
    "exportedFrom": "Rostyman v1.0.0"
  },
  "collections": [ /* full .rostyman collection documents */ ],
  "mockServers": [ ... ],
  "workflows": [ ... ],
  "scheduledJobs": [ ... ],
  "globalVariables": [ ... ],
  "vaultSecrets": [ ... ],
  "browserTests": [ ... ],
  "dbConnections": [ ... ]
}

Required fields​

  • _type — must be "rostyman_workspace"
  • _version — format version (currently "1.0")
  • info.name — workspace name
  • collections — array of Rostyman Collection documents (may be empty)

All other top-level arrays are optional; omit or leave empty if unused.

Collections​

Each entry in collections is a complete rostyman_collection document — same structure as a standalone .rostyman file (see the Collection Format).

"collections": [
  { "_type": "rostyman_collection", "_version": "1.0", "info": { "name": "API" }, "items": [ ... ] }
]

Mock Servers​

"mockServers": [
  {
    "name": "Users API Mock",
    "port": 4001,
    "routes": [ { "method": "GET", "path": "/users", "status": 200, "body": "[]" } ],
    "variables": [
      { "key": "delay", "initialValue": "0", "currentValue": "0", "type": "text", "enabled": true, "description": "" }
    ]
  }
]

routes are driver-defined route objects (method, path, status, body, headers, delay). variables are mock-scoped.

Workflows​

"workflows": [
  {
    "name": "Health Check Pipeline",
    "description": "",
    "nodes": [ { "id": "start-1", "type": "default", "data": { "nodeType": "start" }, "position": { "x": 0, "y": 0 } } ],
    "edges": [ { "id": "e1", "source": "start-1", "target": "req-1", "sourceHandle": "done" } ],
    "viewport": { "x": 0, "y": 0, "zoom": 1 }
  }
]

nodes and edges form the visual workflow graph. viewport is cosmetic (editor pan/zoom). Edge sourceHandle matters for branching nodes — e.g. a loop node's post-loop continuation uses sourceHandle: "done", and a request node's error path uses sourceHandle: "onError".

Scheduled Jobs​

"scheduledJobs": [
  {
    "name": "Nightly smoke",
    "targetType": "collection",
    "targetId": "API",
    "cronExpression": "0 2 * * *",
    "timezone": "UTC",
    "enabled": true,
    "maxRetries": 0,
    "timeoutMs": 30000
  }
]

targetType is one of collection, request, workflow, browser_test. targetId references the target by name within this export (IDs are regenerated on import).

Global Variables​

Device-global variables (shared across all workspaces on import):

"globalVariables": [
  { "key": "apiHost", "initialValue": "api.example.com", "currentValue": "api.example.com", "type": "text", "enabled": true, "description": "", "isSensitive": false }
]

Vault Secrets​

Encrypted-at-rest secrets. Exported with their plaintext value (the file is a local backup; treat it as sensitive — see Security).

"vaultSecrets": [
  { "key": "STRIPE_KEY", "value": "sk_test_…", "description": "", "enabled": true }
]

Browser Tests​

Web Intelligence tests (recorder/replay):

"browserTests": [
  {
    "name": "Open Download",
    "tags": ["demo", "smoke"],
    "steps": [
      { "type": "navigate", "url": "https://example.com/" },
      { "type": "click", "selector": "a.cta", "selectors": ["a.cta"] }
    ]
  }
]

steps are recorded actions (navigate, click, type, assert…, etc.); each has a type plus action-specific fields (selector, url, value, …).

Database Connections​

Device-global DB connections plus their saved queries:

"dbConnections": [
  {
    "name": "Demo Store (SQLite)",
    "plugin_id": "sqlite",
    "config": { "path": "", "timeout": 30 },
    "color": "#003B57",
    "read_only": false,
    "env_tag": null,
    "savedQueries": [
      { "name": "All customers", "query": "SELECT * FROM customers;", "description": "" }
    ]
  }
]
  • plugin_id — driver id: sqlite, postgres, mysql, mariadb, mssql, mongodb, redis, cockroachdb.
  • config — driver-specific connection settings. Credentials are redacted on export (see below).
  • savedQueries — named SQL snippets attached to the connection.

A SQLite connection may also carry the demo-only fields fileName and seedSql: on import, Rostyman creates a fresh SQLite file under its app-data directory, runs seedSql against it, and points config.path at the new file. This lets a shareable workspace ship a ready-to-query sample database.

Security & credentials​

The workspace file is a full local backup / transfer artifact and may contain sensitive data. Two safeguards apply:

  • Database credentials are redacted on export. Passwords, connection strings/URIs, SSH passwords and private keys, and tokens in dbConnections[].config are blanked. The importer re-creates the connection; the user re-enters the secret.
  • Vault secrets and "sensitive" globals are exported in plaintext (they are the backup payload). Treat exported workspace files as secrets: store and share them accordingly.

On import, database connections are deduplicated by name + plugin_id (they are device-global), so re-importing the same workspace will not create duplicates.

Machine-readable schema​

JSON Schema (draft 2020-12):

{
  "$schema": "https://docs.rostyman.com/schema/rostyman-workspace-1.0.schema.json",
  "_type": "rostyman_workspace",
  "_version": "1.0",
  "info": { "name": "My Workspace" },
  "collections": []
}

Schemas leave additionalProperties open — importers ignore unknown fields, so newer exports still validate and import in older readers.

Design principles​

The same principles as the Collection Format apply: no internal IDs (regenerated on import), variables stay as {{placeholders}}, a single pretty-printed JSON file, and forward-compatibility via ignored unknown fields.