feat: remove incomplete Thread access types (#65) - #185
Conversation
73ca76a to
6d0ff4b
Compare
The Thread access types (`Thread:STRUCTURED` and `Thread:TLV`) were added as an explicitly incomplete "beta definition" in camaraproject#64 and were never finished: they had no capability-discovery example, no `Thread:TLV` example or test, a dead `thread-tlv-example` anchor carrying a `mode` key that the schema's `additionalProperties: false` would have rejected, and a contradiction between `operationalDataset.maxLength` (255) and `maxDatasetLength.maximum` (254). The follow-up that was meant to complete them (camaraproject#65) never happened. Remove them before the public release cycle rather than ship them as-is. - Drop `ThreadStructuredAccessDetail` and `ThreadTlvAccessDetail`, and their `oneOf` branches and `discriminator.mapping` entries on `AccessDetail`. - Drop `SupportedThreadStructuredAccessType`, `SupportedThreadTlvAccessType` and `ThreadAccessTypeProperties`, and the matching enum values, `oneOf` branches and `discriminator.mapping` entries on `SupportedAccessType`. - Reduce `accessDetails.maxItems` and `supportedAccessTypes.maxItems` from 4 to 2, matching the size of the remaining access-type union. - Replace the Thread create example with `TrustDomainCreateWpaEnterprise` and rename `TrustDomainResponseWiFiThread` to `TrustDomainResponseMultiAccess`, so the spec keeps a non-WPA-Personal create example and a two-entry `accessDetails` example. `Wi-Fi:WPA_ENTERPRISE` previously had no example anywhere despite being a supported access type. - Retarget createTrustDomain scenario 03 to WPA-Enterprise and point the discriminator-mismatch scenario at a Wi-Fi value. Thread remains a wanted capability; a follow-up issue records exactly what was removed so it can be reinstated once a vendor implements it.
6d0ff4b to
f34a899
Compare
clundie-CL
left a comment
There was a problem hiding this comment.
See the comment, we'll want to coordinate #180 and this PR. I'm also looking into release management details because it's not clear to me how a breaking change between a release candidate and an initial public release gets formally handled. Whether we need a new release candidate or if it's okay if we just bump the target version, I'm kind of digging into that as well.
There was a problem hiding this comment.
Heads up on PR sequencing — #180 touches this same file/example.
#180 (open) reworks this exact examples block: it splits _imported_examples into "request fragments" (may carry writeOnly data) and "response fragments" (writeOnly fields omitted) — see the block comment at the top of TrustDomains.yaml. It also currently touches this same example under its pre-rename name, TrustDomainResponseWiFiThread.
I'd suggest #180 lands first — it's the file-wide hygiene fix, and landing #185 first would just move that same rebase work onto #180 instead of resolving it here.
Once rebased onto #180, worth aligning the new wifi-wpa3-enterprise-example anchor with the convention it establishes. To be clear, this isn't an active leak — WpaEnterpriseDetail has no writeOnly property today (just authServer and securityModeType), so sharing the anchor between the create and response examples doesn't expose anything right now. But #180 sets a precedent for exactly this situation with the Thread anchor: kept as a single shared fragment, with a comment explaining why sharing is safe and what would force a split. Would suggest doing the same here rather than leaving it unannotated — either that, or split it into a request/response pair like the WPA-Personal examples, whichever you'd prefer.
What type of PR is this?
What this PR does / why we need it:
Removes the Thread access types (
Thread:STRUCTURED,Thread:TLV) from both API definitionsbefore the public release cycle.
Thread was added in #64 (closing #33) as an explicitly incomplete beta definition — the PR note at
the time was "I added to the models but not the examples yet until a vendor implements." #65 was
opened to supply that missing usage and documentation, and never got it; it is now rescoped to
removal. The gaps are still present today:
thread-tlv-exampleis a dead YAML anchor, never aliased by any example, and it carries amode: tlvkey thatThreadTlvAccessDetail(additionalProperties: false) would reject.ThreadTlvAccessDetail.operationalDataset.maxLengthis255whileThreadAccessTypeProperties.maxDatasetLength.maximumis254.Thread:TLVhas no example and no test scenario anywhere.network-access-management:isolated-networks:thread:*scopes added by feat: adds the ability to provision a Thread network #64 were droppedin a later refactor and never replaced.
Changes:
ThreadStructuredAccessDetail/ThreadTlvAccessDetailand theironeOfbranches and
discriminator.mappingentries onAccessDetail; droppedSupportedThreadStructuredAccessType/SupportedThreadTlvAccessType/ThreadAccessTypePropertiesand the matching enum values,oneOfbranches anddiscriminator.mappingentries onSupportedAccessType.accessDetails.maxItemsandsupportedAccessTypes.maxItems4 → 2, matchingthe size of the remaining access-type union.
TrustDomainCreateWpaEnterpriseandrenamed
TrustDomainResponseWiFiThread→TrustDomainResponseMultiAccess. This keeps anon-WPA-Personal create example and the spec's only two-entry
accessDetailsexample.Wi-Fi:WPA_ENTERPRISEpreviously had no example anywhere despite being supported.createTrustDomainscenario 03 to WPA-Enterprise (no renumbering) andpointed the discriminator-mismatch scenario at a Wi-Fi value.
info.descriptionglossaries andcode/README.md. CHANGELOG files are untouched.Which issue(s) this PR fixes:
Fixes #65
Does this PR introduce a breaking change?
Two
accessTypevalues (Thread:STRUCTURED,Thread:TLV) are removed fromAccessDetailandfrom
GET /trust-domains/capabilities, andmaxItemsonaccessDetails/supportedAccessTypesdrops from 4 to 2. Any consumer sending or matching those values is affected. Both APIs are at
rcand no vendor implements Thread today, so no deployed integration is expected to depend onthem.
Special notes for reviewers:
coupled constants, the four defects not to reinstate, and the
#33 → #64 → #65lineage. It alsopoints at Device Capabilities #116, which holds a second, never-reconciled Thread vocabulary (
Thread-NetworkKey,PASE/CASE,supportedNetworkTypes) deleted fromDomain/Capabilities.yamlin 115 refactor per commonalities 577 #117 — anyonerestoring Thread has two half-designs to unify, not one.
TrustDomainCreateWpaEnterpriseexample was validated againstWiFiWpaEnterpriseAccessDetail/WpaEnterpriseDetail. The enterprise anchor uses a distinctSSID so the two-entry response example does not describe a single SSID running WPA3-Personal and
WPA3-Enterprise simultaneously.
channelwas aThread-only property and nothing in the API models a channel any more.
redocly lint: 0 errors, 9 warnings — unchanged frommain.Warning
Silent interaction with #174. That PR rewrites the same
accessDetailsprose to state"at least one entry is always required (
minItems: 1, at mostmaxItems: 4)". This PR changesmaxItemsto2. The two merge without a git conflict, leavingmaxItems: 2in the schemaand "at most
maxItems: 4" in the prose 18 lines below it. Whichever lands second must correctthat sentence by hand — no linter will catch it.
Changelog input
Additional documentation
This section can be blank.