Support examples in <property-group>

[RaySinnema]

We have examples now in <representation>, but that is just unstructured text. For the structured data in a <property-group> that doesn't work very well. We want tools to be able to understand the structure of the example and work with that. For instance, these structured examples could be used to generate a skeleton server or a test client.

Here's one possible approach:

<property-group name="item" uri="http://schema.org/Product">
  <property name="name" uri="http://schema.org/name"/>
  <property name="size" uri="http://schema.org/height"/>
  <property name="milk" uri="http://www.productontology.org/doc/Milk"/>
  <property name="price" uri="http://schema.org/price" type="number"/>
  <property name="currency" uri="http://schema.org/priceCurrency"/>
  <examples>
    <example name="latte">
      <property name="name" value="caffe latte"/>
      <property name="size" value="grande"/>
      <property name="milk" value="whole"/>
      <property name="price" value="2.75"/>
      <property name="currency" value="USD"/>
    </example>
    <example name="macchiato">
      ...
    </example>
  </examples>
</property-group>

There are some complexities because of repeats, references and nesting.

Here's how we could handle repeats and references:

<property-group name="menu" uri="http://schema.org/menu">
  <property-group name="item" ref="item" repeats="true"/>
  <examples>
    <example name="latte">
      <property name="item" example="latte"/>
      <property name="item" example="macchiato"/>
    </example>
  </examples>
</property-group>

Here's how we could handle nesting:

<property-group name="foo">
  <property-group name="bar">
    <property name="baz"/>
  </property-group>
  <examples>
    <example name="gnu">
      <property name="bar">
        <property name="baz" value="gnat"/>
      </property>
    </example>
  </examples>
</property-group>

[gentlewind]

It's useful but also brings the further complexity for RADL creators. Per my experience, REST client developers tend to read representation samples (e.g. for HAL) to construct the REST requests. What are the use cases that tools need to work with these samples directly?

[RaySinnema]

As I wrote above,

these structured examples could be used to generate a skeleton server or a test client.

Furthermore, structured examples can help with #4. Finally, with a generated server and test client, we can also record the examples as they appear in representations.