Summary
Rename the required device key in device metadata to name, matching the key the WhoAmI registry already uses for the same value, and constrain it with the identifier pattern the registry applies.
Motivation
The same pair of facts is recorded in two places under different words. schema/device.json requires both whoAmI and device, while the WhoAmI registry keys an entry by the identifier and calls the same value name. So the identifier half already agrees between the two schemas and the name half does not. For the Behavior device that means whoAmI: 1216 with device: Behavior in its metadata, against 1216 with name: Behavior in the registry.
Any tool that resolves a device from the identity it reports on the wire has to read both files and translate between two words for one value. A device GUI launcher is the immediate case, since it reads WhoAmI from a connected device and needs the canonical device name to locate what to install, but the same applies to any conformance or inventory tool that joins the two sources.
There is a second, independent reason. whoami.json constrains name with pattern ^[a-zA-Z][a-zA-Z0-9_]*$, while device is typed only as string. That value generates namespaces, class names, and the firmware DEVICE_NAME define, so an unconstrained string is a latent failure rather than mere looseness: prose written there produces invalid identifiers in generated code, and nothing rejects it at authoring time.
A third reason is the weakest and would not justify the change alone. A key called device reads as though it holds a device, when it holds a name.
Detailed Design
schema/device.json renames the required device property to name, keeps "type": "string", and adds "pattern": "^[a-zA-Z][a-zA-Z0-9_]*$" to match the registry.
Across the levels the standard spans, device hardware is unaffected. Microcontroller firmware is affected only through regeneration, since the value feeds the DEVICE_NAME define in the generated C scaffolding. High-level software interfaces are affected through the generated C# and Python interfaces and through the two object models that read the metadata. Data formats are unaffected, since neither the wire protocol nor the log format carries this key.
The generators need no alias on the C# side. MetadataDeserializer applies CamelCaseNamingConvention, so name binds directly to a Name member.
The generator must accept the new key before any metadata file uses it. There is direct precedent. MetadataDeserializer builds YamlDotNet without IgnoreUnmatchedProperties, so any unmatched key throws, which is why the top-level description added in August 2026 had to wait for generator support before appearing in a device.yml. The same constraint applies here in reverse, and it fixes the ordering:
- The generators accept both
name and device, and release.
- Device repositories migrate their metadata and regenerate through
harp.toolkit generate interface.
- The schema marks
device deprecated once every published metadata file has moved.
device is removed in a later major schema revision.
On step 3, deprecated is an annotation keyword introduced in JSON Schema draft 2019-09, and all four schema files declare draft-07, so using it means moving $schema forward. Until then the retention can be stated in the property description. Either way it is an annotation rather than a constraint, so it informs an editor through the yaml-language-server directive these files already carry and does not by itself keep anything working.
Drawbacks
A schema change is never a one-repository change. This one obliges every published device.yml, the embedded core register description, the generators object model, the second object model pyharp maintains over the same schema, and a regeneration pass in each device repository.
The benefit is consistency rather than capability, so it competes for review attention against proposals that unblock something currently impossible.
The identifier pattern also rejects metadata that validates today, if any published file carries a name that is not a valid identifier.
Alternatives
Keep the key and rename only the consuming member in the generators, pinning the schema key in place with a YAML alias. This needs no migration and delivers the readability improvement, but it leaves the two schemas disagreeing, which is the part worth fixing.
Rename to deviceName. Rejected because the core register set already declares DeviceName at address 12 with write access, described as storing the user-specified device name. One identifier would then carry both the declared device type and a mutable label that can be overwritten on an individual unit.
Do nothing. The duplication persists, and every tool that joins a reported WhoAmI to a device name keeps translating between two words for one value.
Unresolved Questions
Which mechanism carries the transition in the generators. A single YamlMember alias maps one key per member, so accepting both keys needs either a retained deprecated member or a custom converter on the metadata type. The round-trip assertion in MetadataSerializerTests is the guard against a transition that reads one key and writes the other.
Whether the identifier pattern lands in this change or separately, given it can reject files that validate today.
Design Meetings
None yet.
Summary
Rename the required
devicekey in device metadata toname, matching the key the WhoAmI registry already uses for the same value, and constrain it with the identifier pattern the registry applies.Motivation
The same pair of facts is recorded in two places under different words.
schema/device.jsonrequires bothwhoAmIanddevice, while the WhoAmI registry keys an entry by the identifier and calls the same valuename. So the identifier half already agrees between the two schemas and the name half does not. For the Behavior device that meanswhoAmI: 1216withdevice: Behaviorin its metadata, against1216withname: Behaviorin the registry.Any tool that resolves a device from the identity it reports on the wire has to read both files and translate between two words for one value. A device GUI launcher is the immediate case, since it reads WhoAmI from a connected device and needs the canonical device name to locate what to install, but the same applies to any conformance or inventory tool that joins the two sources.
There is a second, independent reason.
whoami.jsonconstrainsnamewith pattern^[a-zA-Z][a-zA-Z0-9_]*$, whiledeviceis typed only asstring. That value generates namespaces, class names, and the firmwareDEVICE_NAMEdefine, so an unconstrained string is a latent failure rather than mere looseness: prose written there produces invalid identifiers in generated code, and nothing rejects it at authoring time.A third reason is the weakest and would not justify the change alone. A key called
devicereads as though it holds a device, when it holds a name.Detailed Design
schema/device.jsonrenames the requireddeviceproperty toname, keeps"type": "string", and adds"pattern": "^[a-zA-Z][a-zA-Z0-9_]*$"to match the registry.Across the levels the standard spans, device hardware is unaffected. Microcontroller firmware is affected only through regeneration, since the value feeds the
DEVICE_NAMEdefine in the generated C scaffolding. High-level software interfaces are affected through the generated C# and Python interfaces and through the two object models that read the metadata. Data formats are unaffected, since neither the wire protocol nor the log format carries this key.The generators need no alias on the C# side.
MetadataDeserializerappliesCamelCaseNamingConvention, sonamebinds directly to aNamemember.The generator must accept the new key before any metadata file uses it. There is direct precedent.
MetadataDeserializerbuilds YamlDotNet withoutIgnoreUnmatchedProperties, so any unmatched key throws, which is why the top-leveldescriptionadded in August 2026 had to wait for generator support before appearing in adevice.yml. The same constraint applies here in reverse, and it fixes the ordering:nameanddevice, and release.harp.toolkit generate interface.devicedeprecated once every published metadata file has moved.deviceis removed in a later major schema revision.On step 3,
deprecatedis an annotation keyword introduced in JSON Schema draft 2019-09, and all four schema files declare draft-07, so using it means moving$schemaforward. Until then the retention can be stated in the propertydescription. Either way it is an annotation rather than a constraint, so it informs an editor through theyaml-language-serverdirective these files already carry and does not by itself keep anything working.Drawbacks
A schema change is never a one-repository change. This one obliges every published
device.yml, the embedded core register description, the generators object model, the second object model pyharp maintains over the same schema, and a regeneration pass in each device repository.The benefit is consistency rather than capability, so it competes for review attention against proposals that unblock something currently impossible.
The identifier pattern also rejects metadata that validates today, if any published file carries a name that is not a valid identifier.
Alternatives
Keep the key and rename only the consuming member in the generators, pinning the schema key in place with a YAML alias. This needs no migration and delivers the readability improvement, but it leaves the two schemas disagreeing, which is the part worth fixing.
Rename to
deviceName. Rejected because the core register set already declaresDeviceNameat address 12 with write access, described as storing the user-specified device name. One identifier would then carry both the declared device type and a mutable label that can be overwritten on an individual unit.Do nothing. The duplication persists, and every tool that joins a reported WhoAmI to a device name keeps translating between two words for one value.
Unresolved Questions
Which mechanism carries the transition in the generators. A single
YamlMemberalias maps one key per member, so accepting both keys needs either a retained deprecated member or a custom converter on the metadata type. The round-trip assertion inMetadataSerializerTestsis the guard against a transition that reads one key and writes the other.Whether the identifier pattern lands in this change or separately, given it can reject files that validate today.
Design Meetings
None yet.