GenMate.DataModels 41.0.0

POCO Data Models for the GenMate platform.

Reading a property tree — read this before parsing PropertiesJson

MaterialModel.PropertiesJson and its siblings hold a property tree: a JSON object whose keys are property keys (PropertyTypeKeys). A selector's value is a selector node, whose keys are that selector's option names, each addressing that option's property tree.

A PortGroupModel.PropertiesJson, say:

{
  "alarm_current": 0.5,
  "converter_supply_voltage": {
    "$inherit": "circuit_root",
    "25V": { "converter_supply_voltage_value": 25 },
    "70V": { "converter_supply_voltage_value": 70 }
  }
}

An enum property (PropertyDataType.Enum) is not a selector node: its value is a plain string, one of the property type's Options, and it opens no property tree. A port type's "circuit_address_type": "Sensor" is one. It is never asked of the drafter.

A selector node therefore carries metadata alongside its options, sharing one namespace. Keys beginning with $ (PropertyTreeKeys.ReservedPrefix) are metadata and are never options.

The rule

A selector node's options are exactly its non-reserved members. Enumerate them with PropertyTreeKeys.SelectorOptions, never by iterating the node directly.

foreach (var option in PropertyTreeKeys.SelectorOptions(node.EnumerateObject(), p => p.Name))
{
    // option.Name is an option; option.Value is that option's property tree
}

SelectorOptions is generic over the member type, so it works with whatever JSON parser a consumer already uses — this package deliberately ships no parser of its own, keeping its netstandard2.0 target dependency-free.

Iterating a node directly is a real, observed bug and not a hypothetical one: it takes $inherit for an option, renders it as an empty bogus choice, and writes it back as one, corrupting the authored tree on the next save. Any metadata added to this namespace later breaks such a loop the same way — and leaves a SelectorOptions loop working.

Markers defined today

$inherit is authored per authoring object — the material or port group whose property tree it is — not per property key: the device that declares the answer authors the same selector without the marker and is prompted for it as usual, while the devices downstream of it carry the marker and inherit. The same key is therefore inherited on one device and prompted on another, which is why this cannot be a flag on the property definition. It also has to be able to mark a nested selector — converter_supply_voltage authored inside a speaker_wattage branch — which a sibling key at the property level could not address.

An option can never collide with a marker: options are declared only by PropertyTypeDefinition, whose constructor and init accessor reject any option in the reserved namespace. Unrecognised markers should be skipped, not treated as options — which is what SelectorOptions does.

These key strings persist into authored catalogues and customer drawings. Like the enum names in this package, treat them as append-only: add markers, never rename or repurpose one.

Rendering a delete-impact count — read this before displaying a DeleteImpactGroup

DeleteImpactResponse answers "what will deleting this break?" as counts, one DeleteImpactGroup per relationship. Every group ships both label forms, labelPlural and labelSingular:

{
  "referenceType": "port-type",
  "labelPlural": "Port types allowing it",
  "labelSingular": "Port type allowing it",
  "effect": 0,
  "customManagedDistinctionApplies": true,
  "count": 1,
  "countCustom": 1,
  "countManaged": 0
}

There is deliberately no field called label. An asymmetric pair invites a caller to reach for the general-sounding one and render "1 port types allowing it" — the exact bug this shape exists to prevent.

The rule

Pick labelSingular when the count is exactly 1 and labelPlural otherwise, then render it verbatim. Never derive either form from the other.

A count of 0 takes labelPlural, as English does — "0 materials", not "0 material".

Deriving is not merely discouraged, it does not work. Several of these labels are phrases rather than bare nouns, so singularising the last word gives the wrong answer:

This is a real, observed bug and not a hypothetical one: a client that shipped last-word singularisation rendered "1 managed port types allowing it" and "1 custom materials using those port type".

The labels are prose the API authors, so the API owes both forms in full — including the irregulars and the determiners. A client's only job is to choose between them by the count.

customManagedDistinctionApplies is a fixed property of referenceType, not a reading of the numbers: it says whether "custom" and "managed" mean anything for that kind of record at all, so the wording cannot flicker as the data changes. See the XML docs on DeleteImpactGroup for the per-property detail.