Metadata model rejects published and proposed device.yml fields

[glopesdev]

MetadataDeserializer builds YamlDotNet without IgnoreUnmatchedProperties, so any key the object model does not declare throws instead of being ignored. That strictness is worth keeping, but it makes this repository the first mover for every schema change. A key has to be accepted here before any device.yml can carry it, and therefore before core tooling can prototype a proposal against a real schema file.

Two fields the published schema already defines throw today, and every open schema proposal would throw the moment a device declares its field. Each result below was measured by reading the fragment through MetadataDeserializer at 7e6128c.

Already published, and already rejected

deprecated on a register, declared in registers.json since harp-tech/protocol#154.

YamlException: Property 'deprecated' not found on type 'Harp.Generators.RegisterInfo'.

schema/core.yml on protocol main sets it on seven registers, so this is not hypothetical.

protocolVersion at the root, which core.json marks required.

YamlException: Property 'protocolVersion' not found on type 'Harp.Generators.DeviceMetadata'.

Together these mean the upstream core register schema cannot be read by this generator as published, which is why the embedded src/core.yml carries neither field.

Rejected under the open proposals

hardwareTargets as a sequence, from harp-tech/protocol#172 and its pull request harp-tech/protocol#174, which makes the value either a version or an array of versions. HardwareTargets is a single HarpVersion?.

YamlException: Expected 'Scalar', got 'SequenceStart'

hardwareTargets as objects carrying an architecture, from harp-tech/protocol#66, fails the same way.

maxLength on a register, from harp-tech/protocol#220, which folds in harp-tech/protocol#116.

YamlException: Property 'maxLength' not found on type 'Harp.Generators.RegisterInfo'.

name replacing device, from harp-tech/protocol#230. That proposal already names this constraint and puts generator support first in its migration order.

YamlException: Property 'name' not found on type 'Harp.Generators.DeviceMetadata'.

A three-part version, which harp-tech/protocol#145 and harp-tech/protocol#148 both move toward. firmwareVersion: "1.2.3" throws inside HarpVersionTypeConverter, since HarpVersion carries two components.

A 128-bit payload member mask, from harp-tech/protocol#178, where the InterfaceHash member of the new Version register declares mask: 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF. Mask is an int?, and no integer type in the model could hold this value.

An unknown top-level key, the anchor-hosting pattern a published device already uses, throws on payloadLayouts. This is the schema question in #122 rather than a model gap, and is listed here only so the audit is complete.

What already parses

A 24-bit member mask, 0xFFFFFF on the SdkId member of the same register, since it fits an int. A payload member declaring only an offset and a description. Write-only and event-only access lists, so harp-tech/protocol#163 needs nothing here.

length: 0 also parses, but the model cannot represent it. RegisterInfo.Length is a non-nullable int using zero as the absent marker, so a declared zero and an absent attribute are the same value. That is the model half of harp-tech/protocol#214 and would need settling alongside it.

Model changes implied

• RegisterInfo gains Deprecated and MaxLength.
• DeviceMetadata gains ProtocolVersion, and Name alongside Device for the migration window.
• HardwareTargets becomes a collection accepting a scalar, a sequence, and later an object per target.
• The version type accepts three components, or the model stops using HarpVersion for schema versions.
• PayloadMemberInfo.Mask widens, which is Consider allowing for unsigned 64-bit masks #78 and does not reach 128 bits even so.

Accepting a field is not the same as generating from it, and most of these can be accepted first and interpreted later. Emitting [Obsolete] for deprecated, or framing for maxLength, are separate pieces of work.

A question for the protocol side

The 128-bit mask looks worth challenging rather than accommodating. InterfaceHash sits at offset 12 and covers 16 bytes of a U8 register, and SdkId covers 3 bytes at offset 9, both of which the payload member length attribute added by harp-tech/protocol#204 already expresses directly. A mask wide enough to need arbitrary-precision arithmetic in every object model, to say something a length says in one integer, seems like the wrong instrument. Worth raising on harp-tech/protocol#178 before it merges.

Strictness stays

IgnoreUnmatchedProperties is the one change that would resolve all of this at once and should not be adopted. It is not selective, so a misspelled registars or whoAmi would stop erroring and start being silently dropped. Losing misspelling detection is certain; the field list above is finite and known.

Related issues

• Rename the device key to name for consistency with the WhoAmI registry protocol#230
• Schema for variable-length registers protocol#220
• Interface schema does not allow 0-length payloads protocol#214
• Allow multiple hardware targets in device schema protocol#172
• Use a single version number for protocol releases protocol#148
• Use a single version number in device repositories protocol#145
• Support variable-length registers in device.yml register specifications protocol#116
• Add platform architecture to hardware targets in device schema protocol#66
• Add UID, Tag, Heartbeat and Version registers to core interface specification protocol#178
• Allow multiple hardware targets in device specification protocol#174
• Payload type reuse across registers is unvalidated in both generator targets #122
• Consider allowing for unsigned 64-bit masks #78