Scripts and declarations

How a script is structured, and the difference between request and contract scripts.

Every script is exactly one declaration followed by a body in curly braces. The declaration says what kind of script it is, gives it a name and, for contracts, lists its parameters. Nothing may appear before or after the declaration except comments.

request MyRequest {
    // The script body goes here
}

The body is a sequence of statements that run from top to bottom until a return is reached or the body ends.

Request scripts

A request is a one-off script. You send it to the server, it runs once, and you get its return value back. Requests don’t take parameters.

request HelloWorld {
    return "Hello World!"
}

Run a request by sending it to POST /run.

Contract scripts

A contract is a script that’s saved on the server and invoked later, optionally with parameters.

contract path.to.MyContract@1.2.3(name: string, tags: []string) {
    return "Hello ${name}"
}

A contract declaration has these parts:

Part	Example	Required
Path	path.to	No
Name	MyContract	Yes
Version	@1.2.3	No. Defaults to 1
Parameters	(name: string, tags: []string)	No

• The path is a dot-separated prefix that organizes contracts, like a namespace. Path segments may be any word, including keywords, so contract if.else.Thing is allowed.
• The version is covered in Versioning.
• Parameters are name: type pairs separated by commas, with an optional trailing comma. Parameter names must be unique.
• A contract with no parameters leaves out the parentheses entirely. Writing empty parentheses, (), is an error.

contract reports.DailySummary {
    return "No parameters needed"
}

Inside the body, parameters behave like const variables: you can read them but not reassign them.

Save contracts with POST /contracts. See Contracts for the full workflow.

Return values

Whatever a script returns becomes the returnValue of the HTTP response, encoded as JSON:

request Example {
    return { ok: true, items: [1, 2, 3] }
}

{ "returnValue": { "ok": true, "items": [1, 2, 3] } }

If a script ends without a return, or uses a bare return, the return value is null. See JSON encoding for how each type is represented.