fix(spec): custom actions documentation does not match the schema

[ficosta]

These came up while working through the v1 spec for an implementation. Each one is a
place where the prose and the JSON schemas told me different things and I had to go to
the schemas to find out which to follow, so I am reporting them together.

The custom actions documentation does not match the Manifest schema. Two of these
mismatches produce a Manifest that fails validation if the prose is followed
literally; the rest are wording carried over from neighbouring sections.

I checked the two validation claims below with ajv against the schemas in
v1/specification/json-schemas, rather than by reading alone.

customActions is an array, not a map

Line 159 describes the field as "a Map where the keys correspond to the id of the
custom action and the values are Action objects". In graphics/schema.json,
customActions is "type": "array" with Action items, and Action declares id
as a required property. Line 70 of this same document already says Action[], "An
array of Action objects".

A Manifest written in the map form that line 159 describes is rejected with
must be array. The array form validates.

The field is named customActions, not actions

Lines 158 and 388 both refer to an actions field. The Manifest has no such
property. Its properties are $schema, id, version, main, name,
description, author, customActions, actionDurations, supportsRealTime,
supportsNonRealTime, stepCount, schema, renderRequirements and thumbnails.

Since the schema sets additionalProperties: false, a Manifest that uses the name
actions is not merely unconventional, it is rejected with must NOT have additional properties.

An Action's schema may be null

Line 167 gives the type of the Action schema field as object. lib/action.json
declares it as oneOf an object or null, and its own description says "If the action
does not require any parameters, set this to null". The field table does not mention
that, so a reader working from the table would not know the null case exists.

I put the null case in the description column rather than the type column, because
every other type cell in this document is a bare type name and the document never
escapes a pipe inside a table. If you would rather the type column carried it, say so
and I will change it there instead.

Two lines in customAction() describe a different action

Each action section describes skipAnimation with the verb of its own action:
"transition" for playAction() at line 297, "disappear" for stopAction() at line
346, "update" for updateAction() at line 368. Line 392 gives customAction() the
stopAction() wording, "should disappear", which does not describe an arbitrary
custom action.

Line 396 reads "The returned Promise MUST resolve after the execution of the update",
matching updateAction() at line 372. The next paragraph of the same section, at line
398, was already adapted to "an animation of the action", which suggests a line was
missed rather than an intentional cross-reference.

What changed

Six lines, all in the custom actions material. actions becomes customActions in
both places, the map description becomes an array description, the Action schema
row gains the null case, "should disappear" becomes "should perform the action", and
"the execution of the update" becomes "the execution of the action". No other section
is touched.

Left alone

Lines 389 and 390 already require the Promise to "resolve when the action is
executed", so line 396 restates the same rule. Removing that duplication is an
editorial decision rather than a correction, and it overlaps with the ground the
fix/specification-actions branch was covering, so I have left it as it stands.

Related

The same pass through the spec produced two other things, listed here in case it is
easier to look at them together:

• fix(spec): schema field description omits load() #80 corrects the Manifest schema field description, which names a method that does
  not exist and omits load().
• On docs(api): clarify graphic data validation (Issue #75) #79 I asked whether the Server API section means to grant the Server explicit
  permission to validate params.data, or would rather stay silent on that and only
  cover what happens when data does not conform.

This is the last of the three, so nothing further is queued behind it.

[dvdeurse]

Changes look good to me!