Support usage scenarios

Problem

It’s often useful to describe a series of messages that start at the billboard URI and end when the client’s goal is achieved. This shows the client developer how to achieve the goal and how all the pieces fit together.

Proposed Solution

The state diagram contains most of the information we need. A client achieves a goal by starting at the initial state and following transitions until done. To make the scenario concrete, all we have to add is the input that the client must provide along the way.

Here’s an example of what that could look like:

<scenarios>
  <scenario name="Chrissy orders a latte">
    <documentation>This is the happy path.</documentation>
    <start state="Arrived"/>
    <step transition="Read menu"/>
    <step transition="Place order">
      <properties name="order">
        <properties name="items">
          <properties name="item">
            <property name="name" value="caffe latte"/>
            <property name="size" value="tall"/>
            <property name="milk" value="whole"/>
          </properties>
        </properties>
        <property name="customer" value="Chrissy"/>
      </properties>
    </step>
    <step transition="Pay">
      <properties name="payment">
        <property name="amount" value="2.75"/>
        <property name="currency" value="USD"/>
        <property name="paymentMethod" value="creditCard"/>
        <property name="cardholderName" value="C.C. Conway"/>
        <property name="cardNumber" value="5525366617069778"/>
        <property name="securityCode" value="836"/>
        <property name="expiryMonth" value="06"/>
        <property name="expiryYear" value="2019"/>
      </properties>
    </step>
    <step transition="Take receipt"/>
    <step transition="Receive notification"/>
    <step transition="Take serving"/>
  </scenario>
</scenarios>

The above example can be run against a server, and the HTTP messages exchanged can be recorded for inclusion in the documentation.

Variations

• We could leave out the <properties> used as input and instead rely on examples in the `<data-model>`s.

• Alternatively, we could wrap the <properties> in an <input> element and also add an <output> element, so that we don’t need a running server to capture the messages. This can only work if the stylesheet understands the media type(s) used, however.