Flisk Service Json

---
name: flisk-service-json
description: Read, edit and validate a Flisk `service.json`, the per-service contract every generated file comes from - required fields (`schemaVersion`, `appName`, `appType`, `stack`), `port`, `healthCheckPath`, `dependsOn`, `featuresEnabled`, `params`, `secrets`, routing (`apiPath`, `basePath`, `exposeViaProxy`), build fields, and `command` for services that run without Docker. Use when changing an existing service's ports, dependencies, health check, features or routes, or when doctor reports a service.json field. To create a new service, use flisk-scaffold.
license: MIT
compatibility: Requires the flisk CLI. Does not deploy.
metadata:
  author: flisk-sh
  version: "1.0"
---

# service.json contract

Every resource is one `services/<stack>/<name>/service.json`. Flisk generates the local runtime from it; you never edit the outputs.

## Workflow

1. Open the file and keep `"$schema": "https://flisk.sh/schema.service.json"` in it for editor completion and inline validation.
2. Required: `schemaVersion` (currently `1`), `appName` (kebab-case, matching the directory), `appType` (`backend`, `frontend`, `worker`, `migrator`, `mcp`, `agent`, `bring-your-own`, `sdk`, `library`) and `stack`.
3. Change only what the task needs:

   | Need | Field |
   | --- | --- |
   | container port, health route | `port`, `healthCheckPath` |
   | start order | `dependsOn` (for example `["postgres", "orders-api-migrator"]`) |
   | Prisma, Drizzle, Playwright and other features | `featuresEnabled` |
   | non-secret config / secret names | `params` / `secrets.required`, `secrets.optional` |
   | route | `apiPath` (backends), `basePath` (frontends), `exposeViaProxy: false` for no route |
   | bring-your-own build | `dockerfile`, `buildContext`, `image`, `restart` |
   | run as a local process without Docker | `command` |

4. Validate: `flisk doctor` (service fields, duplicates, deprecated names) and `flisk config verify` (generated files in sync).
5. Apply: `flisk up <stack>` regenerates the service's `.autogenerated/` files from the new manifest.

## Guardrails

- Never hand-edit `.autogenerated/` files; they are rebuilt from this file.
- Prefer the CLI for new services: `flisk resource` writes a manifest that satisfies the schema.
- `dependencies` and `envVars` are deprecated names for `dependsOn` and `params`; `flisk config migrate` moves old manifests (including `type` to `appType`) to the current schema.
- Do not put secret values or `jwtSecret` here; values go in the project `.env`.
- Schema: [`runtime/engine/schemas/service-schema.json`](https://github.com/flisk-sh/flisk/blob/main/runtime/engine/schemas/service-schema.json). Reference: [docs/service-json.md](https://github.com/flisk-sh/flisk/blob/main/docs/service-json.md).