This page is for developers and assistants that write Shipvo app specs (shipvo.app/v0) and want to check them before a phone opens them. You will validate a spec, read the errors and fix them.
@shipvo/spec holds the JSON Schema and validate(spec). It never throws: errors refuse the spec, warnings are shown but do not. The format is in the app spec design. The full list of checks and the rest of the API are in the @shipvo/spec README.
Check a spec
- Install the package:
npm install @shipvo/spec. - Call
validateon the spec.
import { validate } from "@shipvo/spec";
const { errors, warnings } = validate({
spec: "shipvo.app/v0",
app: { id: "hello", name: "Hello" },
permissions: { network: ["api.example.com"] },
data: { rates: { source: "http", get: "https://other.example.com/rates" } },
screens: [{ id: "home", body: [{ type: "text", value: "Hi" }] }]
});
console.log(errors);Output, from running this on this branch:
[
{
"path": "$.data.rates.get",
"message": "\"other.example.com\" is not declared in permissions.network.",
"fix": "Add \"other.example.com\" to permissions.network."
}
]Each issue has a path (a JSON path to the exact place), a message and a fix you can apply as written. A spec with no problems returns { "errors": [], "warnings": [] }.
Network and write permissions
permissions.network lists the domains the app reads from (data sources). permissions.write lists the domains action steps may call. They are separate so that reading a service never grants writing to it, and each write needs approval.
The schema file ships as @shipvo/spec/schema.json. Give it to an assistant, or put it in an MCP tool description, so specs come out valid the first time.
Troubleshooting
is not declared in permissions.network: thedatasource calls a domain the spec does not list. Add the domain topermissions.network, or point the source at a listed one. For an action step that changes data, usepermissions.write.Interactive block "button" has no label: add a shortlabel. People and assistants find the block by that name.Missing required "get"orUnknown key: an HTTP source usessource: "http"with agetURL. Remove keys the error names and add the ones it asks for.- A string is refused as a possible key: the spec never holds a secret value. Declare the key by name under
secretsand save its value on the phone.
Next steps
- Spec blocks: every block, with examples.
- Describe an app: an assistant writes the spec and validates it for you.
- Glossary: app spec, block and saved key in plain words.