Miscellaneous clarifications identified while developing Flow Runner and Flow Builder

[markboots]

In the course of developing the open-source Flow Runner and Flow Builder implementations, the dev team proposed a list of cleanups and clarifications to the spec. The following suggestions don't significantly change the behaviour or capabilities of the spec, but improve consistency and usability. (Other changes with larger functional implications have been proposed as separate issues.)

1. flow->destination_block can be null, e.g. at the end of a flow path (where there is no next block from an exit).
2. Add "offline" mode in Flow intro docs. (This is referenced in Layer 4, but not on the Flow intro)
3. The spec should use snake_case consistently
4. Add first_block_id [string] to the Flow definition. This is more reliable than relying on block ordering to find the starting block.
5. Block exits: The optional "default" exit should apply generally; this is only discussed on the Case block rather than in the Block definition.
6. Add an optional exit_block_id to the Flow definition. The flow would jump to here on "fatal" errors within blocks.
7. Clarify the list of modes for supported_modes; this indicates the "channel type" that the flow or resource can run through: text (any general channel that supports bi-directional text), sms, ussd, ivr, rich_messaging (data channels that support multimedia including text, audio, images, and video, such as social network chatbots), and offline (mobile apps designed to run offline without a data connection).

[smn]

👍 on making the first block & exit blocks more explicit. Is there a reason the exit_block_id is optional? When would one not want one and would an exit block value of null be more explicit if an exit block isn't needed?

[markboots]

Is there a reason the exit_block_id is optional? When would one not want one and would an exit block value of null be more explicit if an exit block isn't needed?

Lots of the flows we see from our users don't have an "exit handling" section of blocks. Rather, they just follow the wires until getting to the point where there are no more blocks, and then the flow ends. An exit handling section of the flow (jumped to via exit_block_id) was seen as optional.

We could enforce that the exit_block_id key must exist, but can be null for no exit handling. Is there a preference for that over interpreting no exit_block_id key as null?

[markboots]

Two additional cleanups the dev team proposed from experience on the open-source Flow Runner and Flow Builder:

1. Change the block namespace separator from \ to ., to avoid needing to double-escape it in languages that use \ as an escape character (and challenges with multiple layers of escaping).
2. Rename platform_metadatato vendor_metadata for better clarity; platform has many ambiguous meanings.