feat: split API into Network Access Devices + Trust Domains (#152)

[clundie-CL]

⚠️ Draft — blocked on decisions. This PR is for alignment, not yet mergeable. It's waiting on a naming decision that cascades into follow-up commits and dictates how the failing CAMARA validation gets resolved. Reviewers: read "Open decisions & status" under Special notes for reviewers before reviewing file-by-file.

What type of PR is this?

• enhancement/feature

What this PR does / why we need it:

Splits the single network-access-management.yaml spec into two independent CAMARA APIs, per #152:

New spec	Endpoints	Purpose
code/API_definitions/network-access-devices.yaml	/network-access-devices, /reboot-requests	Operator-supplied managed equipment: device info + reboot lifecycle
code/API_definitions/trust-domains.yaml	/trust-domains, /trust-domains/{id}/devices, /services	Network segments, connectivity/access policy, device registration/onboarding, services

The two functional halves share no operations and no domain schemas. Shared definitions (NAM_Common, CAMARA_common, and ServiceSite) stay in code/modules/ and code/common/ and are $ref'd + bundled into each spec — the same mechanism already used for the other shared modules. Each spec gets its own info.title, server basePath (/network-access-devices/vwip, /trust-domains/vwip), tag set, and a per-API-scoped info.description. Both pass redocly lint.

Which issue(s) this PR fixes:

Fixes #152

Does this PR introduce a breaking change?

• Yes
• No

Splitting the single network-access-management API into two APIs is breaking by definition: the original API and its server basePath ({apiRoot}/network-access-management/vwip) are removed and replaced by {apiRoot}/network-access-devices/vwip and {apiRoot}/trust-domains/vwip, each with its own spec, scopes, and release lifecycle. Any consumer integrated against the prior API must migrate to the two replacements. (Currently, the only consumer is CableLabs)

Special notes for reviewers:

⚠️ Open decisions & status (read first)

This PR is intentionally not yet mergeable — it exists to align on the split and, specifically, on naming. The items below cascade: each unblocks the next, and the last is what clears the failing check.

1. Naming — the gating decision.

   • API A (network segments + device registration + services): trust-domains vs isolated-networks (or other)? Working name in this PR is trust-domains.
   • API B (operator equipment + reboots): confirm network-access-devices.

2. What the naming decision drives (subsequent commits to this PR): rename the spec file, server basePath, and info.title; the readiness-checklist filename; the scope-string prefixes (still network-access-management:* today); and re-homing the 20 .feature files (filenames, header spec URLs, tag prefixes).

3. How that clears CI. The only blocking check is [P-022] — release-plan.yaml must change in its own PR. A split couples release-plan.yaml (the api_names) with the spec files, so the green path is a sequenced delivery: (a) a standalone release-plan-only PR declaring the final names, then (b) this PR (files/docs) with no release-plan change. We can't do (a) until names are locked. Every other finding in the run is a non-blocking warning/hint.

TL;DR for reviewers: please weigh in on the naming options (#1). Everything downstream — including making CI green — follows from that.

Docs updated alongside the split:

• release-plan.yaml → two apis: entries (network-access-devices, trust-domains). ⚠️ Worth release-management eyes since this drives release automation.
• code/README.md → folder diagram, two-spec lint/bundle commands, File Purposes + which modules each API uses (and which are shared).
• code/Test_definitions/README.md → bundle command updated to point at the two new specs (the previously referenced network-access-management.yaml is removed).
• Readiness checklist split into network-access-devices-API-Readiness-Checklist.md + trust-domains-API-Readiness-Checklist.md.

Explicitly deferred:

• Re-prefixing/re-homing the 20 .feature files (filenames, header spec URLs, @network_access_management_* tag prefixes) per API — mechanical, deferred until names are final to avoid churning 20 files on a working name. The operation→API mapping is firm — it follows the existing tag groups: Services / Trust Domains / Trust Domain Devices → trust-domains; Network Access Devices / Reboot Requests → network-access-devices.
• Deep info.description reconciliation (bubbling up embedded schema docs) — tracked in Refactor API Description for RC release #143. This PR only trims the description so each API's prose is coherent for its own scope.

misc: root README.md release links point at the r2.1 tag (historical, unaffected); CHANGELOG untouched (gated/historical).

Changelog input

 release-note
Split the Network Access Management API into two APIs: Network Access Devices (device info + reboot requests) and Trust Domains (segments, policy, device registration, services). API names are provisional pending #152.

Additional documentation

This section can be blank.

docs

[clundie-CL]

@caubut-charter @benhepworth @hdamker — opening this one up for discussion. 👋

This is a draft PR (not for merge) that splits the current Network Access Management API into two independent APIs: one for operator-supplied devices + reboots, one for the network-segmentation / Trust Domain side. I'd appreciate your eyes for alignment, primarily on naming, before we take it further. The full context, what's changing and the open decisions, is in the PR description. Please start with the "⚠️ Open decisions & status (read first)" section.

Two things I'm specifically after:

Naming. network-access-devices feels settled for the device/reboot API. For the other one I used trust-domains as a working name, but the more I sit with it, the more I think network-access-segments is the better fit. It keeps the network-access-* family lineage alongside network-access-devices, and it lets Trust Domain stay as the core resource/schema rather than the API name (the API's real capability is network-access segmentation). It also reads more cleanly for scopes — e.g. network-access-segments:trust-domains:…. Keen on everyone's take, and open to alternatives.

@hdamker: Since the split couples release-plan.yaml (the api_names) with the spec files, the one blocking validation finding is [P-022] (release-plan must change in its own PR). My read is the clean path is a sequenced delivery: (1) a standalone release-plan PR declaring the final names first, then (2) this files/docs PR, but I'd really value your guidance on how you'd like this to proceed from a release-management standpoint before we lock anything in. (The red CI here is expected for that reason.)

Mainly want to converge on the naming so the downstream commits, and the validation fix, can follow. Thanks all!

[benhepworth]

I like your idea of prefixing things with network-access to keep it inline instead of the two discussed on last week's call (network-access-devices / trust-domains).

@albertoramosmonagas - is there anything we need to do from an API Backlog perspective when we split this API into two? Both APIs will still be in this repo and are both within the original scope of NetworkAccessManagement - it just makes sense to split into two different yaml files in this repo since some people implementing may want to do one without the other.

[clundie-CL]

@benhepworth Talked some more and think some candidates are:

network-access-segments — Pro: "segment" cleanly conveys a bounded grouping that policy can be applied to, which matches how Trust Domains function as containers for connectivity, QoS, and security policy. Con: "segment" is a generic networking term and doesn't signal that the API specifically covers policy-bearing groupings rather than arbitrary partitions.

network-access-domains — Pro: aligns naturally with the Trust Domain resource concept, reinforcing a consistent domain-based vocabulary across the API. Con: "domain" is overloaded in networking (DNS, broadcast, security, etc.) and may require disambiguation in docs.

network-access-isolation — Pro: outcome-focused and carries continuity with the resource's original "Isolated Networks" naming, so the underlying intent is preserved even as the resource itself was renamed. Con: less natural as a resource-noun, and "isolation" can imply hard separation when the API may express more nuanced access policies.

[albertoramosmonagas]

Hi @benhepworth,

My understanding is that this is not a repository split, but an internal split of the API definition within the existing NetworkAccessManagement repository.

From an API Backlog perspective, I do not see a need for a new Backlog action as long as both resulting API definitions remain within the originally approved NetworkAccessManagement scope and no new repository or new out-of-scope capability is introduced.

The relevant work seems to be on the Release Management side. The two API names should be reflected in release-plan.yaml, each API should have its own YAML under code/API_definitions/, and the required readiness assets should be checked per API.

So I would only bring this back to API Backlog if the split introduces new scope, a new repository, a change of ownership/lifecycle, or a potential overlap with other CAMARA APIs.

CC: @tanjadegroot, @hdamker

[hdamker]

@hdamker: Since the split couples release-plan.yaml (the api_names) with the spec files, the one blocking validation finding is [P-022] (release-plan must change in its own PR). My read is the clean path is a sequenced delivery: (1) a standalone release-plan PR declaring the final names first, then (2) this files/docs PR, but I'd really value your guidance on how you'd like this to proceed from a release-management standpoint before we lock anything in. (The red CI here is expected for that reason.)

@clundie-CL good question, as this is a hen-egg situation (if you define an API in rc status the release-plan.yaml PR would get red if the API YAML does not yet exist). The mechanism I have implemented is the "draft" status of an API:

• defining in a dedicated release-plan.yaml PR the target API names, all defined as "draft" (this state allows that the API YAML is not yet there)
• then do the restructure/renaming of the APIs, e.g. with this PR here
• set the target_api_status back to rc (or alpha) to get the full validation again

Another way you can choose (if the original defined API will be still present):

• do the restructure of the APIs here in the PR, but without the release-plan.yaml changes ... you will get warnings about "orphaned YAML files" (the APIs not yet listed)
• run the release-plan.yaml PR to align the plan with the new structure

BTW: even errors are not blocking a PR merge, they block only a release. But it is recommended to keep the main branch free of errors.

Another hint: you should delete the legacy API Readiness Checklist ... it is obsolete and creates a warning if present.

Happy to support in this special operation if there are further questions!