Skip to content

docs: align actor terminology with CAMARA (#87) - #187

Open
caubut-charter wants to merge 1 commit into
camaraproject:mainfrom
caubut-charter:87-align-camara-actor-terms
Open

docs: align actor terminology with CAMARA (#87)#187
caubut-charter wants to merge 1 commit into
camaraproject:mainfrom
caubut-charter:87-align-camara-actor-terms

Conversation

@caubut-charter

Copy link
Copy Markdown
Contributor

What type of PR is this?

  • documentation

What this PR does / why we need it:

Aligns actor terminology in both specs with CAMARA, per #87. The repository used several competing
labels for the two CAMARA roles — "Network Operator", "API client", and bare "provider" / "client"
— and the casing of "API Consumer" / "API Provider" varied between Title Case and lowercase.

The Commonalities glossary defines API Producer (alternative term API Provider) and
API Consumer, and has no entry for "Network Operator", so the role senses are normalised onto
the CAMARA terms:

  • "Network Operator" → "API Provider" wherever it denoted the entity implementing or operating the
    API, including both # Comments for Network Operators headings and the in-text cross-reference
    to one of them.
  • "API client" / "API Clients" → "API Consumer" wherever it denoted the role, including both
    # Comments for API Clients headings.
  • Bare "provider" / "providers" / "clients" qualified to the full role names.
  • Casing normalised to Title Case across specs, modules, user stories and test definitions.

Deliberately not renamed:

  • "network-operator-supplied" equipment and the commercial "relationship between a network operator
    and a subscriber". These describe hardware provenance and account relationships, not the API
    role — upstream CAMARA_common.yaml uses "network operator" the same way, in the same sentence
    as "API Consumer" and "API Provider".
  • "API client" in the OAuth client_id / resource-ownership sense ("created by the calling API
    client"), which is how the CAMARA API Design Guide uses that phrase. 32 such occurrences are
    preserved.

Glossary repairs made along the way:

  • Subscriber was used 40+ times across both specs and defined in neither. Added, noting that
    the specification uses it interchangeably with Service Owner.
  • Service was referenced by the Service Owner and Service Site entries in the devices spec
    without being defined there. Added.
  • Network Operator is retained but reworded to state the equipment and account relationship
    explicitly instead of duplicating API Provider. It is still referenced by four other glossary
    entries, so deleting it would have left an undefined term.
  • "API client operator", a garbled compound occurring exactly once, corrected to API Consumer.
  • "Network Client Devices", a dangling resource name used once and defined nowhere, corrected to
    Trust Domain Devices.
  • Two list operations named their scoping subject differently ("service owner" vs "subscriber");
    unified on subscriber.

Which issue(s) this PR fixes:

Fixes #87

Does this PR introduce a breaking change?

  • Yes
  • No

Special notes for reviewers:

  • Scoped to the issue title (full audit) rather than the narrowed comment, per maintainer direction.
  • Text inside the CAMARA:MANDATORY markers is generated from info-description-templates.yaml
    and is left byte-identical — verified block-by-block against code/common/. The four remaining
    lowercase occurrences all live there and are intentional.
  • CPE: already absent repo-wide, so the "make sure to remove CPE" part of [Trust Domains] Align documentation with CAMARA actors and terms #87 needs no change
    and Remove CPE to remove network specific terms #14 can stay closed.
  • redocly lint: 0 errors, 9 warnings — unchanged from main.
  • One judgement call worth a second opinion: the new Subscriber entry states that this
    specification uses Subscriber and Service Owner interchangeably. That is deliberately
    descriptive rather than normative — if the two are meant to be distinct roles, this entry is the
    place to say so.
  • Conflicts with docs: document empty-list, 400/422, and GENERATE credential conventions (#129) #174 (code/API_definitions/*.yaml, TrustDomainDevices.yaml, TrustDomains.yaml)
    and with the Remove incomplete thread specification #65 branch (network-access-domains.yaml, TrustDomains.yaml). All are
    prose-adjacent and mechanical to resolve.

Deferred, not done here: Service Owner casing in the user stories, scope-table wording
("other clients" vs "other API clients"), and an ambiguous "created by" attachment in the
reboot-request list description.

Changelog input

release-note Aligned actor terminology with CAMARA: Network Operator and API client are now API Provider and API Consumer where they denote the CAMARA roles, with added Subscriber and Service glossary entries and two dangling terms corrected.

Additional documentation

This section can be blank.

docs

The specs used several competing labels for the two CAMARA actor roles:
"Network Operator", "API client" and bare "provider"/"client" all stood in
for what CAMARA calls the API Provider and the API Consumer, and the casing
of both terms varied between Title Case and lowercase.

The CAMARA Commonalities glossary defines "API Producer" (alternative term
"API Provider") and "API Consumer", and has no entry for "Network Operator",
so the role senses are normalised onto the CAMARA terms:

- "Network Operator" -> "API Provider" wherever it denoted the entity that
  implements or operates the API, including both "# Comments for Network
  Operators" headings and the cross-reference to one of them.
- "API client"/"API Clients" -> "API Consumer" wherever it denoted the role,
  including both "# Comments for API Clients" headings. Left untouched in the
  OAuth `client_id`/resource-ownership sense ("created by the calling API
  client"), which is how the CAMARA API Design Guide uses the phrase.
- Bare "provider"/"providers"/"clients" qualified to the full role names.
- Casing normalised to Title Case for both roles across the specs, modules,
  user stories and test definitions.

"network-operator-supplied" and the commercial "relationship between a
network operator and a subscriber" are kept: these describe real-world
equipment provenance and account relationships, not the API role, and
upstream CAMARA_common.yaml uses "network operator" the same way. The
**Network Operator** glossary entry is therefore retained but reworded to
state that relationship explicitly rather than duplicating **API Provider**.

Glossary repairs made along the way:

- **Subscriber** was used 40+ times in both specs but defined in neither.
  Added, and noted that this specification uses it interchangeably with
  **Service Owner**.
- **Service** was referenced by the Service Owner and Service Site entries in
  the devices spec without being defined there. Added.
- "API client operator", a garbled compound appearing exactly once, corrected
  to API Consumer.
- "Network Client Devices", a dangling resource name used once and defined
  nowhere, corrected to Trust Domain Devices.
- Two list operations described their scoping subject differently
  ("service owner" vs "subscriber"); unified on subscriber.

Text inside the CAMARA:MANDATORY markers is generated from Commonalities and
is left byte-identical, so the four lowercase occurrences there are retained
deliberately.

@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.

Minor change requested. Should land this one last after #185

operationId: getRebootRequests
description: |
This endpoint returns a list of Reboot Requests associated with the service owner created by the calling API client.
This endpoint returns a list of Reboot Requests associated with the subscriber and created by the calling API client.

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.

API client -> API Consumer

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.

[Trust Domains] Align documentation with CAMARA actors and terms

2 participants