Exercise · Portability

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

For the Pico you have been modeling across Part 3, write the beginning of a portable Pico definition that keeps the Open Engineering identity separate from the runtime identity:

# portable-pico.yaml
oepid: oep.pico.alice.v1
identity:
  type: did
  public:
    method: webvh
    url: https://engine-a.example.com/picos/alice/did.json
relationships:
  identity:
    method: peer
messaging:
  protocol: didcomm
authorization:
  mechanism: channel-policy

Answer the questions below.

Note

This example follows the shape from the lesson. The important point is that identity should become a first-class property of a Pico rather than an implementation-specific extension.

Success criteria

• Your definition keeps the Open Engineering identifier (oepid) separate from the runtime did:webvh.
• You separate identity, relationships, messaging, and authorization into distinct sections.
• You can name at least two of the four remaining-work areas that stand between this definition and a fully portable Pico.

Automatable check

Validate your definition parses:

pico parse portable-pico.yaml --out /tmp/pp.json \
  && echo "OK: portable Pico definition parses"

The command exits 0 and prints the OK: line when well-formed.

Reflect

• Why must the Open Engineering identifier and the runtime DID remain distinct?
• What would “losing a cryptographic key should not mean losing the Pico” require of an implementation?

Next

Continue with the Lab.