registry: RangeController, ModeController, ToggleController with resources, presets and semantics

The three generic controllers are described in full and leave the stub table (62 stubs remain). A declaration
takes an instance name, friendly names from text() and asset(), and the options of the interface: range, unit and
presets for a range; supportedModes and ordered for a mode; semantics() for all three, with actions mapped to
directives and states mapped to a value or a range of values.

Refused at device.add(), each with the endpoint, interface and instance in the message: no instance name or no
friendly name; an instance declared twice; a first friendly name or a phrase used by another capability of the
endpoint; a reserved word, an asset id that is not in the catalog; range.max not above range.min; a preset off the
precision grid or outside the range; fewer than two modes or a mode listed twice; a mapping to a directive the
interface does not have, to a payload that does not fit, to a mode that is not listed, to AdjustMode on modes
that are not ordered; SetEcoOn, SetEcoOff, EcoOn and EcoOff on anything but a toggle.

For 1.x callers: Alexa.RangeController lists rangeValue (1.5.2 sent supported: []); addSupportedModes() announces
a mode given as a string as { value } and notes it, and takes { ordered: false } as a second argument, the default
stays true as 1.5.2 sent it (device.add() defaults to false). Declared the 1.x way, the zoo fan and curtain give
the same JSON as before.

Tests: the zoo blind, whose range, unit and semantics were written by hand into the JSON of 1.5.2, is declared
with device.add() and equals that JSON plus the Alexa capability; five capability objects of Amazon's examples
are reproduced the same way. 27 examples of four pages added. npm test: 108 pass (was 85) in 10.5-11.3 s, also on
Node 18.20.8 and 20.20.2.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

src/compat/AlexaInterface.ts

@@ -2,7 +2,7 @@ import { Capability } from "../device/Capability.js";
 import type { CapabilityJson } from "../device/Capability.js";
 import { registry } from "../registry/index.js";
 import { text } from "../registry/resources.js";
-import type { Semantics } from "../registry/types.js";
+import type { Label, Semantics } from "../registry/types.js";
 import type { ActionMapping } from "./ActionMapping.js";
 import type { AlexaInterfaceType } from "./enums.js";
 
@@ -14,7 +14,8 @@ export interface SupportedMode {
 
 interface Options {
   semantics?: Semantics;
-  supportedModes?: Array<string | SupportedMode>;
+  supportedModes?: Array<{ value: string; friendlyNames: Label[] }>;
+  ordered?: boolean;
 }
 
 /**
@@ -43,9 +44,18 @@ export class AlexaInterface extends Capability<any, any, Options> {
     this.friendlyNames.push(text(name, locale));
   }
 
-  /** The modes of a ModeController, as { value, modeResources } objects. */
-  addSupportedModes(modes: Array<string | SupportedMode>): void {
-    this.options.supportedModes = modes;
+  /**
+   * The modes of a ModeController, as { value, modeResources } objects. A mode given as a string is announced as
+   * { value } and noted: Alexa wants friendly names for it. ordered is true unless options.ordered says otherwise,
+   * as 1.x announced every mode list; with device.add() the default is false.
+   */
+  addSupportedModes(modes: Array<string | SupportedMode>, options: { ordered?: boolean } = {}): void {
+    this.options.ordered = options.ordered ?? true;
+    this.options.supportedModes = modes.map((mode) => {
+      if (typeof mode !== "string") return { value: mode.value, friendlyNames: (mode.modeResources?.friendlyNames ?? []) as Label[] };
+      this.notes.push(`the mode ${mode} was given as a string, pass { value, modeResources }`);
+      return { value: mode, friendlyNames: [] };
+    });
   }
 
   setInstance(name: string): void {

src/device/validate.ts

@@ -118,6 +118,15 @@ export function checkCapability(capability: Declared<unknown>, descriptor: AnyDe
     if (friendlyNames.length > 0) refuse("takes no friendly names");
   }
 
+  // A capability of device.add() passed the schema when it was declared; one declared the 1.x way did not
+  if (descriptor.options) {
+    try {
+      descriptor.options.parse(capability.options);
+    } catch (err) {
+      refuse(err instanceof SchemaError ? err.message : String(err));
+    }
+  }
+
   // generic-controllers.html, "Semantics for user utterances": "Each semantic phrase must be unique across all
   // controller instances for each endpoint"
   const used = new Map<string, Declared>();

src/index.ts

@@ -8,9 +8,11 @@ export type { CapabilityJson, CommonOptions, Declaration } from "./device/Capabi
 
 // The interfaces, for device.add(), and the registry that holds them by name
 export { registry, DeclarationError, SchemaError } from "./registry/index.js";
-export { Alexa, BrightnessController, TemperatureSensor } from "./registry/index.js";
+export {
+  Alexa, BrightnessController, ModeController, RangeController, TemperatureSensor, ToggleController,
+} from "./registry/index.js";
 export { PowerController, EndpointHealth } from "./compat/enums.js";
-export { asset, text } from "./registry/resources.js";
+export { asset, text, semantics, SemanticsBuilder } from "./registry/index.js";
 
 // The vocabularies of the Smart Home API
 export {
@@ -21,7 +23,7 @@ export type {
   ActionId, AssetId, DisplayCategoryName, StateId, UnitOfMeasure,
   ActionsToDirective, AnyDescriptor, CapabilityExtras, Declared, DirectiveDescriptor, EndpointView, EventDescriptor,
   InterfaceDescriptor, Label, PropertyDescriptor, Semantics, StatesToRange, StatesToValue,
-  Infer, Schema, Temperature, TimeInterval,
+  ActionName, StateName, Mode, Infer, Schema, Temperature, TimeInterval,
 } from "./registry/index.js";
 
 // 1.x

src/registry/index.ts

@@ -2,8 +2,11 @@
 import { Alexa } from "./interfaces/Alexa.js";
 import { BrightnessController } from "./interfaces/BrightnessController.js";
 import { EndpointHealth } from "./interfaces/EndpointHealth.js";
+import { ModeController } from "./interfaces/ModeController.js";
 import { PowerController } from "./interfaces/PowerController.js";
+import { RangeController } from "./interfaces/RangeController.js";
 import { TemperatureSensor } from "./interfaces/TemperatureSensor.js";
+import { ToggleController } from "./interfaces/ToggleController.js";
 import { STUBS } from "./interfaces/stubs.js";
 import { DeclarationError } from "./types.js";
 import type { AnyDescriptor } from "./types.js";
@@ -12,8 +15,11 @@ const described: readonly AnyDescriptor[] = [
   Alexa,
   BrightnessController,
   EndpointHealth,
+  ModeController,
   PowerController,
+  RangeController,
   TemperatureSensor,
+  ToggleController,
 ];
 
 const descriptors = new Map<string, AnyDescriptor>();
@@ -42,7 +48,14 @@ export const registry = {
   },
 };
 
-export { Alexa, BrightnessController, EndpointHealth, PowerController, TemperatureSensor };
+export {
+  Alexa, BrightnessController, EndpointHealth, ModeController, PowerController, RangeController, TemperatureSensor,
+  ToggleController,
+};
+export type { Mode } from "./interfaces/ModeController.js";
+export { asset, text } from "./resources.js";
+export { semantics, SemanticsBuilder } from "./semantics.js";
+export type { ActionName, StateName } from "./semantics.js";
 export { DeclarationError, defineInterface } from "./types.js";
 export type {
   ActionsToDirective, AnyDescriptor, CapabilityExtras, Declared, DirectiveDescriptor, EndpointView, EventDescriptor,

src/registry/interfaces/ModeController.ts

@@ -0,0 +1,95 @@
+import { labels } from "../resources.js";
+import { at, mismatch, s } from "../schema.js";
+import type { Schema } from "../schema.js";
+import { semanticsOf } from "../semantics.js";
+import { DeclarationError, defineInterface } from "../types.js";
+import type { Label } from "../types.js";
+
+const directives = {
+  SetMode: { name: "SetMode", payload: s.object({ mode: s.string({ min: 1 }) }) },
+  AdjustMode: {
+    name: "AdjustMode",
+    payload: s.object({ modeDelta: s.optional(s.number({ integer: true })) }),
+    // alexa-modecontroller.html, "Capabilities object": "Modes that have an order support the AdjustMode directive."
+    when: ({ options }: { options: { ordered?: boolean } }) => options.ordered === true,
+    note: "modeDelta is the number of modes to move by, 1 when it is left out",
+  },
+};
+
+/** One mode: its value and what the user calls it. */
+export interface Mode {
+  value: string;
+  friendlyNames: Label[];
+}
+
+// A mode is declared as { value, friendlyNames }. The object of discovery and of 1.x, { value, modeResources:
+// { friendlyNames } }, is taken as well.
+const eitherForm = s.object({
+  value: s.string({ min: 1 }),
+  friendlyNames: s.optional(s.unknown()),
+  modeResources: s.optional(s.object({ friendlyNames: s.unknown() })),
+}, { unknownKeys: "reject" });
+const mode: Schema<Mode> = {
+  expects: "a mode { value, friendlyNames }",
+  parse(input, path = "") {
+    if (typeof input !== "object" || input === null) throw mismatch(path, mode.expects, input);
+    const { value, friendlyNames, modeResources } = eitherForm.parse(input, path);
+    const named = friendlyNames === undefined && modeResources ? "modeResources.friendlyNames" : "friendlyNames";
+    return { value, friendlyNames: labels.parse(friendlyNames ?? modeResources?.friendlyNames, at(path, named)) };
+  },
+};
+
+/**
+ * One of a list of values, under an instance name: the wash cycle of a washer, the position of a garage door. Amazon
+ * certifies a garage door only with this interface and the display category GARAGE_DOOR.
+ */
+export const ModeController = defineInterface({
+  namespace: "Alexa.ModeController",
+  version: "3",
+  doc: "https://developer.amazon.com/docs/alexaplus/device-apis/alexa-modecontroller.html",
+  kind: "controller",
+  tier: 1,
+  instanced: true,
+  properties: {
+    mode: { name: "mode", value: s.nullable(s.string({ min: 1 })), note: "null when no mode is set, as when the device is off" },
+  },
+  directives,
+  options: s.object({
+    /** At least two. When the modes have an order, in increasing order. */
+    supportedModes: s.array(mode, { min: 2 }),
+    /** The modes have an order, cold to hot, and the user can say "increase": Alexa sends AdjustMode. Default: false. */
+    ordered: s.optional(s.boolean()),
+    semantics: s.optional(semanticsOf({ directives, stateValue: s.string({ min: 1 }) })),
+  }, { unknownKeys: "reject" }),
+  // A capability declared the 1.x way may be without modes, or have modes without names
+  discovery({ options: { supportedModes = [], ordered = false } }) {
+    if (supportedModes.length === 0) return {};
+    const modes = supportedModes.map(({ value, friendlyNames = [] }) => (
+      friendlyNames.length > 0 ? { value, modeResources: { friendlyNames } } : { value }
+    ));
+    return { configuration: { ordered, supportedModes: modes } };
+  },
+  validate(capability) {
+    const { supportedModes, ordered = false, semantics } = capability.options;
+    const values = supportedModes.map(({ value }) => value);
+    const twice = values.find((value, i) => values.indexOf(value) !== i);
+    if (twice !== undefined) throw new DeclarationError(capability, `the mode ${twice} is listed twice`);
+    const isMode = (value: unknown): boolean => values.includes(value as string);
+
+    for (const { directive } of semantics?.actionMappings ?? []) {
+      if (directive.name === "AdjustMode" && !ordered) {
+        throw new DeclarationError(capability, "an action is mapped to AdjustMode, which needs ordered: true");
+      }
+      if (directive.name === "SetMode" && !isMode(directive.payload?.mode)) {
+        throw new DeclarationError(capability, `an action is mapped to SetMode ${directive.payload?.mode}, the modes are ${values.join(", ")}`);
+      }
+    }
+    for (const mapping of semantics?.stateMappings ?? []) {
+      if (mapping["@type"] === "StatesToValue" && !isMode(mapping.value)) {
+        throw new DeclarationError(capability, `a state is mapped to ${mapping.value}, the modes are ${values.join(", ")}`);
+      }
+    }
+  },
+  errorNamespace: "Alexa.Safety",
+  errorTypes: ["OBSTACLE_DETECTED", "SAFETY_BEAM_BREACHED"],
+});

src/registry/interfaces/RangeController.ts

@@ -0,0 +1,75 @@
+import { UNITS_OF_MEASURE } from "../catalog.js";
+import { labels } from "../resources.js";
+import { s } from "../schema.js";
+import { semanticsOf } from "../semantics.js";
+import { DeclarationError, defineInterface } from "../types.js";
+
+const directives = {
+  SetRangeValue: { name: "SetRangeValue", payload: s.object({ rangeValue: s.number() }) },
+  AdjustRangeValue: {
+    name: "AdjustRangeValue",
+    payload: s.object({ rangeValueDelta: s.number(), rangeValueDeltaDefault: s.boolean() }),
+    note: "rangeValueDeltaDefault is true when the user named no amount; rangeValueDelta is then the precision",
+  },
+};
+
+// 0.1 + 0.2 is not 0.3: a value is on the grid when it is within a millionth of a step of it
+function onGrid(value: number, origin: number, step: number): boolean {
+  const steps = (value - origin) / step;
+  return Math.abs(steps - Math.round(steps)) < 1e-6;
+}
+
+/**
+ * A number in a range, under an instance name: the position of a blind, the speed of a fan. With nonControllable it
+ * is a reading the user can ask for, like an air quality index.
+ */
+export const RangeController = defineInterface({
+  namespace: "Alexa.RangeController",
+  version: "3",
+  doc: "https://developer.amazon.com/docs/alexaplus/device-apis/alexa-rangecontroller.html",
+  kind: "controller",
+  tier: 1,
+  instanced: true,
+  properties: {
+    rangeValue: { name: "rangeValue", value: s.number() },
+  },
+  directives,
+  options: s.object({
+    /** precision is the step of the range and what "turn up the fan speed" changes it by. */
+    range: s.object({ min: s.number(), max: s.number(), precision: s.number({ gt: 0 }) }, { unknownKeys: "reject" }),
+    unit: s.optional(s.oneOf(UNITS_OF_MEASURE, "a unit of measure like Alexa.Unit.Percent")),
+    /** Names for values: "set the fan speed to maximum". */
+    presets: s.optional(s.array(s.object({ value: s.number(), friendlyNames: labels }, { unknownKeys: "reject" }))),
+    semantics: s.optional(semanticsOf({ directives, stateValue: s.number(), ranges: true })),
+  }, { unknownKeys: "reject" }),
+  // A capability declared the 1.x way may be without a range; check() says so, discovery lists what there is
+  discovery({ options: { range, unit, presets } }) {
+    const configuration = {
+      ...(range && { supportedRange: { minimumValue: range.min, maximumValue: range.max, precision: range.precision } }),
+      ...(unit && { unitOfMeasure: unit }),
+      ...(presets && { presets: presets.map(({ value, friendlyNames }) => ({ rangeValue: value, presetResources: { friendlyNames } })) }),
+    };
+    return Object.keys(configuration).length > 0 ? { configuration } : {};
+  },
+  validate(capability) {
+    const { range: { min, max, precision }, presets = [], semantics } = capability.options;
+    const inRange = (value: number): boolean => value >= min && value <= max;
+    if (max <= min) throw new DeclarationError(capability, `range.max ${max} is not above range.min ${min}`);
+    for (const { value } of presets) {
+      // alexa-rangecontroller.html, "Preset object": "minimum range value + (n x precision) where n is an integer"
+      if (!inRange(value) || !onGrid(value, min, precision)) {
+        throw new DeclarationError(capability, `the preset ${value} is not ${min} + n x ${precision}, up to ${max}`);
+      }
+    }
+    for (const { directive } of semantics?.actionMappings ?? []) {
+      const { rangeValue } = directive.payload ?? {};
+      if (directive.name === "SetRangeValue" && !inRange(rangeValue as number)) {
+        throw new DeclarationError(capability, `an action is mapped to SetRangeValue ${rangeValue}, the range is ${min} to ${max}`);
+      }
+    }
+  },
+  // alexa-rangecontroller.html, "SetRangeValue directive error handling": "If your error is safety related, respond
+  // with an Alexa.Safety.ErrorResponse"
+  errorNamespace: "Alexa.Safety",
+  errorTypes: ["OBSTACLE_DETECTED", "SAFETY_BEAM_BREACHED"],
+});

src/registry/interfaces/ToggleController.ts

@@ -0,0 +1,30 @@
+import { s } from "../schema.js";
+import { semanticsOf } from "../semantics.js";
+import { defineInterface } from "../types.js";
+
+const directives = {
+  TurnOn: { name: "TurnOn", payload: s.object({}) },
+  TurnOff: { name: "TurnOff", payload: s.object({}) },
+};
+
+/**
+ * Something that is on or off, under an instance name: the oscillation of a fan, the light of an oven. The one
+ * generic controller that Alexa hunches work with (SetEcoOn, SetEcoOff, EcoOn, EcoOff).
+ */
+export const ToggleController = defineInterface({
+  namespace: "Alexa.ToggleController",
+  version: "3",
+  doc: "https://developer.amazon.com/docs/alexaplus/device-apis/alexa-togglecontroller.html",
+  kind: "controller",
+  tier: 1,
+  instanced: true,
+  properties: {
+    toggleState: { name: "toggleState", value: s.enum("ON", "OFF") },
+  },
+  directives,
+  options: s.object({
+    semantics: s.optional(semanticsOf({ directives, stateValue: s.enum("ON", "OFF"), hunches: true })),
+  }, { unknownKeys: "reject" }),
+  errorNamespace: "Alexa.Safety",
+  errorTypes: ["OBSTACLE_DETECTED", "SAFETY_BEAM_BREACHED"],
+});

src/registry/interfaces/stubs.ts

@@ -51,7 +51,6 @@ const TABLE: readonly Row[] = [
   ["Alexa.Media.PlayQueue", "1", [], "alexa-media-playqueue.html"],
   ["Alexa.Media.Playback", "1", [], "alexa-media-playback.html"],
   ["Alexa.Media.Search", "1", [], "alexa-media-search.html"],
-  ["Alexa.ModeController", "3", ["mode"], "alexa-modecontroller.html"],
   ["Alexa.MotionSensor", "3", [], "alexa-motionsensor.html"],
   ["Alexa.PercentageController", "3", [], "alexa-percentagecontroller.html"],
   ["Alexa.PlaybackController", "3", [], "alexa-playbackcontroller.html"],
@@ -59,7 +58,6 @@ const TABLE: readonly Row[] = [
   ["Alexa.PowerLevelController", "3", [], "alexa-powerlevelcontroller.html"],
   ["Alexa.ProactiveNotificationSource", "1", [], "alexa-proactivenotificationsource.html"],
   ["Alexa.RTCSessionController", "1", [], "alexa-rtcsessioncontroller.html"],
-  ["Alexa.RangeController", "3", [], "alexa-rangecontroller.html"],
   ["Alexa.RecordController", "3", [], "alexa-recordcontroller.html"],
   ["Alexa.RemoteVideoPlayer", "1", [], "alexa-remotevideoplayer.html"],
   ["Alexa.SceneController", "3", [], "alexa-scenecontroller.html"],
@@ -77,14 +75,13 @@ const TABLE: readonly Row[] = [
   ["Alexa.ThermostatController.Schedule", "1", [], "alexa-thermostatcontroller-schedule.html"],
   // "UNKNOWN" in 1.5.2 as well; the page is titled "Interface 3"
   ["Alexa.TimeHoldController", "3", [], "alexa-timeholdcontroller.html"],
-  ["Alexa.ToggleController", "3", ["toggleState"], "alexa-togglecontroller.html"],
   ["Alexa.UIController", "1", [], "alexa-uicontroller.html"],
   ["Alexa.UserPreference", "1", [], "alexa-userpreference.html"],
   ["Alexa.VideoRecorder", "1", [], "alexa-videorecorder.html"],
   ["Alexa.WakeOnLANController", "1", [], "alexa-wakeonlancontroller.html"],
 ];
 
-// What 1.5.2 added to the capability object of three of them
+// What 1.5.2 added to the capability object of two of them
 const EXTRAS: Record<string, AnyDescriptor["discovery"]> = {
   // No properties object; supportsDeactivation and proactivelyReported on the capability itself
   "Alexa.SceneController": ({ proactivelyReported }) => ({
@@ -94,9 +91,6 @@ const EXTRAS: Record<string, AnyDescriptor["discovery"]> = {
   "Alexa.ThermostatController": () => ({
     configuration: { supportedModes: ["HEAT", "COOL", "AUTO", "OFF"], supportsScheduling: false },
   }),
-  "Alexa.ModeController": ({ options }) => (options.supportedModes?.length > 0
-    ? { configuration: { ordered: true, supportedModes: options.supportedModes } }
-    : {}),
 };
 
 function kindOf(namespace: string): AnyDescriptor["kind"] {

src/registry/resources.ts

@@ -1,7 +1,7 @@
 // Friendly names: what the user calls an instance, a mode or a preset (resources-and-assets.html).
 import { ASSETS, RESERVED_WORDS } from "./catalog.js";
 import type { AssetId } from "./catalog.js";
-import { at, s, SchemaError } from "./schema.js";
+import { at, mismatch, s, SchemaError } from "./schema.js";
 import type { Schema } from "./schema.js";
 import type { Label } from "./types.js";
 
@@ -28,6 +28,7 @@ const reserved: readonly string[] = RESERVED_WORDS;
 export const label: Schema<Label> = {
   expects: "a friendly name, from text() or asset()",
   parse(input, path = "") {
+    if (typeof input !== "object" || input === null) throw mismatch(path, label.expects, input);
     const { "@type": type, value } = typed.parse(input, path);
     if (type === "asset") return { "@type": type, value: assetValue.parse(value, at(path, "value")) };
     const named = textValue.parse(value, at(path, "value"));

src/registry/semantics.ts

@@ -0,0 +1,135 @@
+// Semantics of a generic controller: the phrases "open", "close", "raise", "lower" mapped to directives, and states
+// like "open" and "closed" mapped to values of the property (alexa-discovery-objects.html, "Semantics object").
+import { ACTIONS, STATES } from "./catalog.js";
+import type { ActionId, StateId } from "./catalog.js";
+import { at, mismatch, s, SchemaError } from "./schema.js";
+import type { Schema } from "./schema.js";
+import type { ActionsToDirective, Directives, Semantics, StatesToRange, StatesToValue } from "./types.js";
+
+type Short<Id extends string, Prefix extends string> = Id extends `${Prefix}${infer Name}` ? Name : never;
+/** A phrase by its id or by its name: "Alexa.Actions.Open" or "Open". */
+export type ActionName = ActionId | Short<ActionId, "Alexa.Actions.">;
+/** A state by its id or by its name: "Alexa.States.Closed" or "Closed". */
+export type StateName = StateId | Short<StateId, "Alexa.States.">;
+
+const listed = <T>(given: T | readonly T[]): T[] => (Array.isArray(given) ? [...given] : [given as T]);
+const withPrefix = (prefix: string, name: string): string => (name.startsWith(prefix) ? name : `${prefix}${name}`);
+
+/**
+ * Collects the mappings of one capability:
+ *
+ *   semantics()
+ *     .action("Close", "SetRangeValue", { rangeValue: 0 })
+ *     .action(["Open", "Raise"], "SetRangeValue", { rangeValue: 100 })
+ *     .state("Closed", 0)
+ *     .stateRange("Open", 1, 100)
+ *
+ * What is collected is checked when the capability is declared, against the directives and the property of its
+ * interface.
+ */
+export class SemanticsBuilder implements Semantics {
+  readonly actionMappings: ActionsToDirective[] = [];
+  readonly stateMappings: Array<StatesToValue | StatesToRange> = [];
+
+  /** The phrases send the directive. payload is its payload; leave it out for a directive that has none. */
+  action(actions: ActionName | readonly ActionName[], directive: string, payload?: Record<string, unknown>): this {
+    this.actionMappings.push({
+      "@type": "ActionsToDirective",
+      actions: listed(actions).map((name) => withPrefix("Alexa.Actions.", name)),
+      directive: payload === undefined ? { name: directive } : { name: directive, payload },
+    });
+    return this;
+  }
+
+  /** The property at this value is in these states: "is the garage door open?" */
+  state(states: StateName | readonly StateName[], value: unknown): this {
+    this.stateMappings.push({ "@type": "StatesToValue", states: listed(states).map((name) => withPrefix("Alexa.States.", name)), value });
+    return this;
+  }
+
+  /** The property between the two values, both included, is in these states. For an interface with a numeric property. */
+  stateRange(states: StateName | readonly StateName[], minimumValue: number, maximumValue: number): this {
+    this.stateMappings.push({
+      "@type": "StatesToRange",
+      states: listed(states).map((name) => withPrefix("Alexa.States.", name)),
+      range: { minimumValue, maximumValue },
+    });
+    return this;
+  }
+}
+
+export function semantics(): SemanticsBuilder {
+  return new SemanticsBuilder();
+}
+
+export interface SemanticsRules {
+  /** The directives of the interface: a mapping names one of them and gives its payload. */
+  directives: Directives;
+  /** The value of the property a state stands for. */
+  stateValue: Schema<unknown>;
+  /** States can be mapped to a range of values: the property is a number. */
+  ranges?: boolean;
+  /**
+   * SetEcoOn, SetEcoOff, EcoOn and EcoOff can be mapped. "Semantics for Alexa hunches is supported only for
+   * Alexa.ToggleController" (generic-controllers.html).
+   */
+  hunches?: boolean;
+}
+
+const isHunch = (id: string): boolean => /\.(SetEcoOn|SetEcoOff|EcoOn|EcoOff)$/.test(id);
+
+/** The schema of the semantics option of one interface. It takes a semantics() builder or the object as discovery has it. */
+export function semanticsOf({ directives, stateValue, ranges = false, hunches = false }: SemanticsRules): Schema<Semantics> {
+  const allowed = <Id extends string>(ids: readonly Id[], what: string): Schema<Id[]> => {
+    const choice = ids.filter((id) => hunches || !isHunch(id));
+    return s.array(s.oneOf(choice, `${what}: ${choice.map((id) => id.split(".")[2]).join(", ")}`), { min: 1 });
+  };
+  const names = Object.keys(directives);
+  const lists = s.object({ actionMappings: s.optional(s.array(s.unknown())), stateMappings: s.optional(s.array(s.unknown())) });
+  const action = s.object({
+    "@type": s.literal("ActionsToDirective"),
+    actions: allowed(ACTIONS, "a phrase of Alexa.Actions"),
+    directive: s.object({ name: s.oneOf(names, `a directive of the interface: ${names.join(", ")}`) }),
+  });
+  const state = s.object({
+    "@type": ranges ? s.enum("StatesToValue", "StatesToRange") : s.enum("StatesToValue"),
+    states: allowed(STATES, "a state of Alexa.States"),
+  });
+  const range = s.object({ minimumValue: s.number(), maximumValue: s.number() }, { unknownKeys: "reject" });
+
+  function actionMapping(input: unknown, path: string): ActionsToDirective {
+    const mapping = action.parse(input, path);
+    const { name, payload } = mapping.directive as ActionsToDirective["directive"];
+    // Checked as the directive will arrive; a mapping without a payload stays without one in discovery
+    const checked = directives[name].payload.parse(payload ?? {}, at(path, "directive.payload"));
+    return { "@type": mapping["@type"], actions: mapping.actions, directive: payload === undefined ? { name } : { name, payload: checked } };
+  }
+
+  function stateMapping(input: unknown, path: string): StatesToValue | StatesToRange {
+    const mapping = state.parse(input, path) as StatesToValue | StatesToRange;
+    if (mapping["@type"] === "StatesToValue") {
+      return { "@type": mapping["@type"], states: mapping.states, value: stateValue.parse(mapping.value, at(path, "value")) };
+    }
+    const { minimumValue, maximumValue } = range.parse(mapping.range, at(path, "range"));
+    if (minimumValue > maximumValue) throw new SchemaError(at(path, "range"), `the minimumValue ${minimumValue} is above the maximumValue ${maximumValue}`);
+    return { "@type": mapping["@type"], states: mapping.states, range: { minimumValue, maximumValue } };
+  }
+
+  const expects = "semantics() with at least one action or state";
+  return {
+    expects,
+    parse(input, path = "") {
+      if (typeof input !== "object" || input === null) throw mismatch(path, expects, input);
+      const { actionMappings = [], stateMappings = [] } = lists.parse(input, path);
+      if (actionMappings.length + stateMappings.length === 0) throw mismatch(path, expects, {});
+      const parsed: Semantics = {};
+      if (actionMappings.length > 0) {
+        parsed.actionMappings = actionMappings.map((mapping, i) => actionMapping(mapping, `${at(path, "actionMappings")}[${i}]`));
+      }
+      if (stateMappings.length > 0) {
+        parsed.stateMappings = stateMappings.map((mapping, i) => stateMapping(mapping, `${at(path, "stateMappings")}[${i}]`));
+      }
+      return parsed;
+    },
+  };
+}

src/registry/types.ts

@@ -125,7 +125,11 @@ export interface InterfaceDescriptor<
   events?: Record<string, EventDescriptor>;
   /** What a declaration can set beyond the fields every capability has: a range, the supported modes. */
   options?: Schema<O>;
-  discovery?: (capability: Declared<O>) => CapabilityExtras;
+  /**
+   * What the interface adds to the capability object. The options may be incomplete: a capability declared the
+   * 1.x way is announced with what it has, and check() of its device says what is missing.
+   */
+  discovery?: (capability: Declared<Partial<O>>) => CapabilityExtras;
   /** The event that answers a directive when it is not Alexa / Response (Arm -> Arm.Response). */
   responseFor?: (directive: string) => { namespace: string; name: string; payload?: Schema<any> } | undefined;
   /** The namespace an ErrorResponse goes under when its type is one of errorTypes. */
@@ -133,7 +137,7 @@ export interface InterfaceDescriptor<
   errorTypes?: readonly string[];
   /** Amazon documents a DeferredResponse for the interface. */
   deferrable?: boolean;
-  /** Rules a schema cannot state. Throws DeclarationError. */
+  /** Rules a schema cannot state, for options that passed the schema. Throws DeclarationError. */
   validate?: (capability: Declared<O>, endpoint: EndpointView) => void;
 }