Exercise · Your first Rule

Write and validate one Rule for a Pico.

Reusable exercise exemplar. Demonstrates the exercise convention documented in exercises/index.qmd.

See the Open Engineering Language Server (OELS) onboarding guide for the local install and editor setup.

OELS in your editor

While you work through this content, keep the Open Engineering Language Server (OELS) active in VS Code (or any LSP-capable editor). See the OELS onboarding guide linked at the top of this page (also linked from the academy Resources page) for the one-time install and configuration steps.

What OELS validates. OELS only recognizes OE-shaped YAML/JSON: files with a mapping root that declare an apiVersion beginning with open-engineering.io/, a non-empty kind, and a DNS-1123 metadata.name. Ordinary academy metadata.yaml, Quarto/QMD pages and front matter, Kubernetes/Crossplane/runtime manifests, JSON payload samples, and shell scripts are intentionally non-OE — OELS ignores them silently and you should not add synthetic apiVersion/kind headers to force recognition.

Where you see diagnostics. OELS surfaces UnknownProperty, MissingRequiredProperty, IncorrectType, InvalidEnumValue, MalformedIdentifier, UnknownDefinition, and reference-shape hints in the editor Problems panel as you type. These are independent of quarto render: OELS diagnostics do not block rendering, and Quarto errors do not appear in the Problems panel.

The executable check still comes from this exercise. OELS speeds up editing, but the exercise’s own parser, verifier, or verify.sh (for example the pico parse … command shown below) remains the authoritative success check. Run it as usual.

Task

Write a single Rule for a Pico of your choice. The Rule must:

Have a stable id in the form rule.<slug>.
Declare a kind you would recognize in a real system.
Include a scalar value (a single-line string) the Composer could act on. The reference bin/pico parser only accepts the flat id / kind / value shape used in labs/hello-pico/.

Save it as rules/<your-slug>.yaml.

Success criteria

The file parses as valid YAML.
id, kind, and a payload field are all present.
You can explain, in one sentence, what the Composer would do with this Rule.

Automatable check

Confirm the Rule is well-formed by parsing it with the reference pico CLI shipped in this repository. From the root of your local clone, with the Hello Pico one-time setup applied so pico resolves to bin/pico:

pico parse rules/<your-slug>.yaml --out /tmp/parsed.json \
  && echo "OK: parsed $(basename rules/<your-slug>.yaml)"

The command exits with status 0 and prints an OK: line when the Rule declares the required id, kind, and value fields. Any other exit status means the Rule is missing a required field or uses an unsupported key — re-read the parser error and fix the Rule.

Hints

Show hint

Start from the Hello Pico example in labs/hello-pico/solution.qmd and change the kind and value to something meaningful in your own domain.

Solution sketch

See solution.qmd for a worked example.