Exercise · Introduction

A short, guided task. Complete it before moving on to the lab.

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

TipOELS 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 one-sentence description of a Pico in your own words, and list three examples of things in your day-to-day work that could plausibly be modeled as Picos.

Note

There is no single correct answer. The goal is to internalize the “Rules → Parser → Composer → Pico” mental model from the lesson.

Success criteria

• Your description mentions that a Pico is declarative and composable.
• You can name at least three candidate Picos.
• For at least one candidate, you can sketch what the Rules might look like in YAML.

Automatable check

If you sketched at least one Rule in YAML, save it as rules/<your-slug>.yaml under a scratch working directory and confirm it matches the reference Parser’s flat id / kind / value shape using the pico CLI shipped in this repository (see the Hello Pico one-time setup for the PATH export):

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

The command exits with status 0 and prints an OK: line when the sketch is well-formed. This is an optional accompaniment to the reflection questions — the exercise’s primary goal remains internalizing the mental model, but any YAML you draft can now be mechanically validated.

Reflect

• Which of your three examples is the simplest to model?
• Which one would be the hardest, and why?

Next

Continue with the Lab.