docs: align actor terminology with CAMARA (#87) - #187
Open
caubut-charter wants to merge 1 commit into
Open
Conversation
caubut-charter
requested review from
benhepworth,
clundie-CL and
mayur007
as code owners
August 25, 2026 16:57
caubut-charter
force-pushed
the
87-align-camara-actor-terms
branch
from
August 25, 2026 17:01
6a1a193 to
39429c4
Compare
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.
caubut-charter
force-pushed
the
87-align-camara-actor-terms
branch
from
August 25, 2026 17:06
39429c4 to
ae3b57d
Compare
2 tasks
clundie-CL
requested changes
Aug 26, 2026
clundie-CL
left a comment
Contributor
There was a problem hiding this comment.
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. |
Contributor
There was a problem hiding this comment.
API client -> API Consumer
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What type of PR is this?
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:
API, including both
# Comments for Network Operatorsheadings and the in-text cross-referenceto one of them.
# Comments for API Clientsheadings.Deliberately not renamed:
and a subscriber". These describe hardware provenance and account relationships, not the API
role — upstream
CAMARA_common.yamluses "network operator" the same way, in the same sentenceas "API Consumer" and "API Provider".
client_id/ resource-ownership sense ("created by the calling APIclient"), which is how the CAMARA API Design Guide uses that phrase. 32 such occurrences are
preserved.
Glossary repairs made along the way:
the specification uses it interchangeably with Service Owner.
without being defined there. Added.
explicitly instead of duplicating API Provider. It is still referenced by four other glossary
entries, so deleting it would have left an undefined term.
Trust Domain Devices.
unified on subscriber.
Which issue(s) this PR fixes:
Fixes #87
Does this PR introduce a breaking change?
Special notes for reviewers:
CAMARA:MANDATORYmarkers is generated frominfo-description-templates.yamland is left byte-identical — verified block-by-block against
code/common/. The four remaininglowercase occurrences all live there and are intentional.
and Remove CPE to remove network specific terms #14 can stay closed.
redocly lint: 0 errors, 9 warnings — unchanged frommain.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.
code/API_definitions/*.yaml,TrustDomainDevices.yaml,TrustDomains.yaml)and with the Remove incomplete thread specification #65 branch (
network-access-domains.yaml,TrustDomains.yaml). All areprose-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
Additional documentation
This section can be blank.