Skip to content

feat: remove incomplete Thread access types (#65) - #185

Open
caubut-charter wants to merge 1 commit into
camaraproject:mainfrom
caubut-charter:65-remove-thread-access-types
Open

feat: remove incomplete Thread access types (#65)#185
caubut-charter wants to merge 1 commit into
camaraproject:mainfrom
caubut-charter:65-remove-thread-access-types

Conversation

@caubut-charter

Copy link
Copy Markdown
Contributor

What type of PR is this?

  • cleanup

What this PR does / why we need it:

Removes the Thread access types (Thread:STRUCTURED, Thread:TLV) from both API definitions
before 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-example is a dead YAML anchor, never aliased by any example, and it carries a
    mode: tlv key that ThreadTlvAccessDetail (additionalProperties: false) would reject.
  • ThreadTlvAccessDetail.operationalDataset.maxLength is 255 while
    ThreadAccessTypeProperties.maxDatasetLength.maximum is 254.
  • Thread:TLV has no example and no test scenario anywhere.
  • The three network-access-management:isolated-networks:thread:* scopes added by feat: adds the ability to provision a Thread network #64 were dropped
    in a later refactor and never replaced.

Changes:

  • Schemas — dropped ThreadStructuredAccessDetail / ThreadTlvAccessDetail and their oneOf
    branches and discriminator.mapping entries on AccessDetail; dropped
    SupportedThreadStructuredAccessType / SupportedThreadTlvAccessType /
    ThreadAccessTypeProperties and the matching enum values, oneOf branches and
    discriminator.mapping entries on SupportedAccessType.
  • ConstraintsaccessDetails.maxItems and supportedAccessTypes.maxItems 4 → 2, matching
    the size of the remaining access-type union.
  • Examples — replaced the Thread create example with TrustDomainCreateWpaEnterprise and
    renamed TrustDomainResponseWiFiThreadTrustDomainResponseMultiAccess. This keeps a
    non-WPA-Personal create example and the spec's only two-entry accessDetails example.
    Wi-Fi:WPA_ENTERPRISE previously had no example anywhere despite being supported.
  • Tests — retargeted createTrustDomain scenario 03 to WPA-Enterprise (no renumbering) and
    pointed the discriminator-mismatch scenario at a Wi-Fi value.
  • Prose — removed the Thread mentions from both info.description glossaries and
    code/README.md. CHANGELOG files are untouched.

Which issue(s) this PR fixes:

Fixes #65

Does this PR introduce a breaking change?

  • Yes
  • No

Two accessType values (Thread:STRUCTURED, Thread:TLV) are removed from AccessDetail and
from GET /trust-domains/capabilities, and maxItems on accessDetails /supportedAccessTypes
drops from 4 to 2. Any consumer sending or matching those values is affected. Both APIs are at
rc and no vendor implements Thread today, so no deployed integration is expected to depend on
them.

Special notes for reviewers:

  • Thread is not being abandoned. Issue Restore and Complete Thread Support #183 records the removed YAML verbatim, the
    coupled constants, the four defects not to reinstate, and the #33 → #64 → #65 lineage. It also
    points at Device Capabilities #116, which holds a second, never-reconciled Thread vocabulary (Thread-NetworkKey,
    PASE/CASE, supportedNetworkTypes) deleted from Domain/Capabilities.yaml in 115 refactor per commonalities 577 #117 — anyone
    restoring Thread has two half-designs to unify, not one.
  • The new TrustDomainCreateWpaEnterprise example was validated against
    WiFiWpaEnterpriseAccessDetail / WpaEnterpriseDetail. The enterprise anchor uses a distinct
    SSID so the two-entry response example does not describe a single SSID running WPA3-Personal and
    WPA3-Enterprise simultaneously.
  • "channel restrictions" was dropped from the provider-constraints bullet: channel was a
    Thread-only property and nothing in the API models a channel any more.
  • redocly lint: 0 errors, 9 warnings — unchanged from main.

Warning

Silent interaction with #174. That PR rewrites the same accessDetails prose to state
"at least one entry is always required (minItems: 1, at most maxItems: 4)". This PR changes
maxItems to 2. The two merge without a git conflict, leaving maxItems: 2 in the schema
and "at most maxItems: 4" in the prose 18 lines below it. Whichever lands second must correct
that sentence by hand — no linter will catch it.

Changelog input

release-note Removed the incomplete Thread access types (Thread:STRUCTURED, Thread:TLV) from accessDetails and Trust Domain capability discovery; accessDetails and supportedAccessTypes now allow at most 2 entries, and a Wi-Fi:WPA_ENTERPRISE request example was added.

Additional documentation

This section can be blank.

docs

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.
@caubut-charter
caubut-charter force-pushed the 65-remove-thread-access-types branch from 6d0ff4b to f34a899 Compare August 25, 2026 17:06

@clundie-CL clundie-CL left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Remove incomplete thread specification

2 participants