Skip to content
↑↓ move↵ openesc close

Workspaces

What is on disk

The folders and files Luvin writes in a workspace, what each one is for, and which ones are safe to edit by hand.

4 min read

Luvin stores a workspace as plain text files. You can open them with any editor, compare them and keep them in git. This page lists every file Luvin writes and tells you which ones you can edit yourself.

A workspace with the Pokédex example looks like this:

  • Directorymy-workspace/
    • luvin.yaml workspace manifest
    • Directorypokedex/ a collection
      • collection.yaml collection manifest
      • pokeapi.openapi.yaml contract
      • pokedex-events.asyncapi.yaml contract
      • pokemon.arazzo.yaml Arazzo file with the four workflows
      • Directoryenvironments/
        • local.yaml
      • Directoryscenarios/
        • pokemon.arazzo.yaml inputs and cases of pokemon.arazzo.yaml

Files and folders that start with a dot, like .git, and folders called node_modules are ignored. A collection that uses them also has requests/, flow-auth.yaml and README.md: see the table below.

my-workspace/luvin.yaml
# Workspace de Luvin. Cada colección es una carpeta con su collection.yaml.
version: 1
id: 4f0c6a3e-2b1d-4c58-9a77-0d3a5e9b1c22
name: My workspace
collections:
- pokedex

The comment on the first line is written in Spanish whatever language the app is in. If you set a version in the collection overview, collectionVersion is added to collection.yaml.

File What it holds
luvin.yaml The workspace: its name, a stable id and the list of collection folders.
README.md in the workspace folder The text of the documentation panel on Home.
collection.yaml The visible name of the collection, its optional version and, if you set one, its collection-level authorization (without secret values).
README.md in a collection folder The documentation of the collection. See Write documentation.
Contracts (*.openapi.yaml, *.asyncapi.yaml) The OpenAPI and AsyncAPI files, exactly as you imported or edited them.
Arazzo files (*.arazzo.yaml) The workflows. One file can hold several workflows.
environments/*.yaml One file per environment: base URLs, variables, color and the names of its secrets. See Base URLs, variables and secrets.
scenarios/<arazzo file> The inputs and the cases of each Arazzo file. It has the same name as its Arazzo file.
requests/*.request.yaml One saved request per file. Subfolders of requests/ are the folders you see in the sidebar.
requests/**/_folder.request.yaml Marks a folder of requests and keeps its visible name.
flow-auth.yaml The authorization of workflows, per API and per workflow. Written only when you configure one.
.proto files The definitions that gRPC requests use.

Luvin loads, as contracts or Arazzo files, every .yaml, .yml and .json file of the collection folder, except the ones above that belong to Luvin. Other kinds of file are left alone.

The scenarios/ files use Spanish keys (bases for the starting inputs of each workflow, casos for the cases), whatever language the app is in:

version: 1
bases:
placeOrder:
customerId: C-1001
casos:
- workflow: placeOrder
nombre: Customer without credit
inputs:
customerId: C-0000
espera:
paso: createOrder
status: [402]

Some data never goes into the files:

  • Values of secrets and credentials. They are stored encrypted on the computer. See Privacy and security.
  • Results of runs. They live in the app until you export a report.
  • The Dev Tools log. It lives in memory only.
File By hand?
Arazzo files Yes. The YAML is the source of truth: Luvin keeps what you write. The YAML tab does the same with live validation.
Contracts Yes, in the contract editor or in any editor.
README.md files Yes. It is Markdown.
environments/*.yaml Yes for URLs, variables and color. Never write a secret value there: only its name goes under secrets. To rename an environment, do it in the app, because the file name follows the name.
luvin.yaml Carefully. You can change name and the order or content of collections. Do not change id: the secrets stored on each computer are tied to it, and they would not be found.
collection.yaml You can change name and collectionVersion. Set authorization in the app.
scenarios/*, requests/*, flow-auth.yaml Better in the app. They have a fixed shape and Luvin rewrites them when you change something.

To rename an Arazzo file, use the app: it renames the file in scenarios/ too.