Describing a single parameter across multiple elements (e.g. radio buttons)

[andruud]

Per #22, the author should describe input parameters to a declarative tool using e.g. toolparamdescription (etc):

<input type="text" name="address" toolparamdescription="Street address, excluding postal code">

That works as long as a single element represents a single tool parameter, but this is not the case for e.g. radio buttons:

<input type="radio" name="signal" value="support">
<input type="radio" name="signal" value="neutral">
<input type="radio" name="signal" value="oppose">

Here, the radio group represents a single parameter.

Maybe we just let the toolparamdescription on any one of these elements count as the overall description, but it could be a trap for authors that the description applies to the entire group.

You could also imagine something like an enclosing <fieldset> hosting that attribute, but that fieldset may govern more than just a single radio group, and we'll need some way of associating a "detached" description with the relevant parameter name. I guess we'll need a toolparamname attribute, or something?

<div toolparamname="signal" toolparamdescription="Position on fedoras">
  <input type="radio" name="signal" value="supportive">
  <input type="radio" name="signal" value="neutral">
  <input type="radio" name="signal" value="opposed">
</div>

---

Or, we could avoid the "param" part of toolparamdescription, and just make it a generic tooldescription, then, for the following example:

<fieldset name="fedora" tooldescription="Select your position on fedoras from one of the options, or provide a custom position">
  <legend>Position on fedoras</legend>
  <label>
    <input type="radio" name="signal" value="supportive">
    Supportive
  </label>
  <label>
    <input type="radio" name="signal" value="neutral">
    Neutral
  </label>
  <label>
    <input type="radio" name="signal" value="opposed">
    Opposed
  </label>
  <label>
    <input type="radio" name="signal" value="other">
    Other, please specify:
  </label>
  <input type="text" name="custom-signal" tooldescription="A custom position if no other options fit">
</fieldset>

we send a nested structure, approximately:

{
  "type": "object",
  "properties": {
    "fedora": {
      "type":"object",
      "description": "Select your position on fedoras [...]",
      "properties": {
        "signal": {
          "type":"string",
          "oneOf": [
            { "const": "supportive", "title": "Supportive" },
            { "const": "neutral", "title": "Neutral" },
            { "const": "opposed", "title": "Opposed" },
            { "const": "other", "title": "Other, please specify" }
          ]
        },
        "custom-signal": {
            "type":"string",
            "description": "A custom position if no other options fit"
        }
      }
    }
  }
}

The purpose of signal should then be understood from the description coming from the enclosing fieldset.