Blueprint Language Overview

Blueprint Language is the text form of a RUAL blueprint, in files ending in .blueprint. A person or an AI agent reads and writes it like code. It is about 3 to 5 percent of the size of the blueprint's stored form, and it exports and compiles back exactly.

A blueprint, written as text

On the canvas a blueprint is a graph of blocks and wires. Blueprint Language writes the same graph as text: flow blocks become statements in the order they run, data blocks become expressions written where they are used, and every wire is written once, as a name. This endpoint reads customer_guid and amount from the request body, rejects an amount that is not positive, looks the customer up and creates an order:

blueprint "Orders API"

route POST "orders" -> create-order

fn create-order(connection, params, query, body) {
  let {customer_guid, amount} = body
  guard amount > 0 else {
    reply 400 {error: "INVALID_AMOUNT"}
  }
  customer = get@customers(customer_guid)
  guard customer.accessible else {
    reply 404 {error: "CUSTOMER_NOT_FOUND"}
  }
  order = create@orders(mutations{customer_guid: customer_guid, amount: amount})
  reply 200 order.object
}

On the canvas these sixteen lines are 24 blocks and 28 wires. The source says nothing about which stored block each line is, where it sits on the canvas or which pin each wire enters: that is worked out when the source is compiled.

A few percent of the size, and an exact round trip

Source leaves out everything that is not logic: block identities, the bookkeeping of every wire, and canvas geometry. For a person that means a flow reads as a few dozen lines. For an AI agent it means a whole blueprint fits in its context and a change is a small text edit instead of a rewrite of a large JSON document.

The round trip is exact: a blueprint exports to source, and that source compiles back to the same blocks, wires and settings. Where a shorthand would not reproduce a block exactly, the export writes that block in the plain block form instead, so nothing is lost. One error reply is five blocks on the canvas; in source it is reply 404 {error: "USER_NOT_FOUND"}.

Source and canvas are two views of one blueprint

• Statements are flow blocks, in the order they run. guard amount > 0 else { ... } is a branch, and reply 400 {error: "INVALID_AMOUNT"} is the httpconnection_set_json block with its status code, body and connection.
• Expressions are data blocks, written inline: "INVALID_AMOUNT" is a value_default and amount > 0 a condition_gt.
• Names are outputs. customer.accessible is the accessible output of the block bound to customer, so a wire is written once, where the value is used.
• Positions are optional. An export can write each block's canvas position as a // @xy X,Y pragma at the end of its line. Change the numbers and the block moves; a block without a position is placed automatically.
• Comments are yours. A // comment stays with the statement it belongs to.

A change made in source reaches the canvas as unsaved edits, the same as edits made by hand, and becomes live only when someone saves the blueprint in RUAL Studio. How the blocks then run, which output goes first and what happens on an error, is explained in Block Execution.

Where to use it

Pages in this section

Was this page helpful? Tell us what to improve · RUAL Docs is an integral component of the RUAL ecosystem