Exercise · Cross-Mesh Communication

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 two Picos, one in each of your own meshes, write the subscription configuration that establishes a relationship using the recipient’s did:webvh:

# subscription-a-b.yaml
subscription:
  initiator: did:webvh:https://engine-a.example.com/picos/alice
  recipient: did:webvh:https://engine-b.example.com/picos/bob
  peer:
    initiator: did:peer:rel-alice-bob
    recipient: did:peer:rel-bob-alice

Then write a DIDComm message envelope that would be sent after the subscription is established:

# didcomm-message.yaml
message:
  from: did:peer:rel-alice-bob
  to: did:peer:rel-bob-alice
  type: pico/event
  body:
    event: temperature-reading
    value: 21.5
Note

The exact field names are illustrative. The goal is to internalize the flow from the lesson: resolve → introduce → create peer DIDs → establish subscription → encrypted relationship.

Success criteria

Automatable check

Validate both snippets parse:

pico parse subscription-a-b.yaml --out /tmp/sub.json \
  && echo "OK: subscription parses"
pico parse didcomm-message.yaml --out /tmp/msg.json \
  && echo "OK: message envelope parses"

Both commands exit 0 and print the OK: line when well-formed.

Reflect

  • Why does the message envelope use did:peer rather than did:webvh after the relationship is established?
  • What would change if Pico A and Pico B were in the same mesh?

Next

Continue with the Lab.