Add some description examples

hydra-node/api.yaml

@@ -3,6 +3,19 @@
 "$id": https://raw.githubusercontent.com/input-output-hk/hydra-poc/master/docs/api.json
 "$comment": A synthetic description of the WebSocket API for Hydra Head nodes.
 title: Hydra WebSocket API
+description: >
+  This schema documents the Client API of Hydra Node's Head  protocol, allowing
+  clients to:
+
+    * Perform operations on the head itself, like initialising or closing it,
+    * Submit transactions once the head is open,
+    * Receive notifications from the server node.
+
+  This API takes the form of various JSON data structures that represent either inputs
+  from the client or outputs from the server. It is served over a websocket connection
+  and is fully asynchronous: Inputs from the client are queued for later processing on
+  the server-side, and outputs can occur at any time.
+
 oneOf:
 
 #
@@ -11,6 +24,10 @@ oneOf:
 
 - title: Init
   type: object
+  description: >
+    Initialises a new Head. This command is a no-op when a Head is already open and
+    the server will output an 'CommandFailed' message should this happen.
+
   required:
   - input
   properties:

shell.nix

@@ -53,6 +53,7 @@ let
     cardanoNodePkgs.cardano-cli
     # For validating JSON instances against a pre-defined schema
     pkgs.python3Packages.jsonschema
+    pkgs.yq
   ];
 
   haskellNixShell = hsPkgs.shellFor {