Improve Access and User Consent document

[chrishowell]

What type of PR is this?

documentation

What this PR does / why we need it:

Defines terms and keeps them consistent throughout, improves clarity in English writing.

Which issue(s) this PR fixes:

#98

Special notes for reviewers:

Changelog input

 release-note access-and-user-consent documentation update

Additional documentation

docs

[AxelNennker]

Hi @chrishowell
could you please split the PR into a "better English one" and one or more for consistent use of terms and better definitions?
I would like to get the easy stuff approved and then start the discussion on the rest. Which might still lead to some discussion. Thanks for the PR. I am a bit overwhelmed by it

[jpengar]

@chrishowell @AxelNennker This is a great contribution, thank you Chris!
I agree with Axel, it will be much easier to handle if we isolate the proposed changes in different PRs. The "better English" one will probably be the easiest to approve. However, the one about the terms and definitions (saying that I pretty much agree with the ones you propose), there is a specific #98 issue to revisit terms and definitions and I can imagine that it will require further discussions.

On the other hand, I've labeled the PR with ICM backlog as it would have to be addressed in the next release. We are already closing the second release candidate of current release 0.2.0-rc.2, which is only intended for bug fixes. Also, among the changes you suggested, some of them have greater impact than they look:

• Changing the title of the Purpose section would change the link reference to that section, and would require updating existing references to that section in all other documents in all subprojects that point to it. That's not possible for this meta release at this stage.
• Also, you propose changes to the info.description template, which is included in all CAMARA APIs. This is a very sensitive text to change, as it represents the ICM agreement between many participants. And this text is copied into all API specifications. So if it is changed, it would have to be carefully revised and updated in all API subprojects. So that would certainly be work for another release -> UPDATE: BTW, there is a specific issue to revisit this template *in the backlog The wording in the Mandatory template for info.description is unclear #178

[chrishowell]

Thanks for reviewing :) it's a bit difficult to split this into multiple PRs as the 'better English' comes with using defined terms..

[jpengar]

Thanks for reviewing :) it's a bit difficult to split this into multiple PRs as the 'better English' comes with using defined terms..

@chrishowell As discussed by the team in yesterday's WG call, in order to move things forward, could you split the content of this PR into three:

• One focused on just updating the terms and definitions. So that the WG can agree on the terms to be used in the rest of the documentation. Please keep the same changes you propose in the PR.
• Another editorial one, simply including the same "better English" changes you propose in this PR. You can assume for the moment that the terms and definitions are the ones you proposed. And then it may need some adjustments if something is changed in the previous PR.
• And finally, another independent PR just for changes in the info.description template, which could also fix other issues like The wording in the Mandatory template for info.description is unclear #178.

[jpengar]

FYI @chrishowell @AxelNennker @sebdewet This PR is now split into:

• PR #182 split - terms and definitions (part 1 of 3) #212
• PR #182 split - better english improvements (part 2 of 3) #213
• PR #182 split - info.description template review (part 3 of 3) #214

We may think of closing this PR and finishing the work in the others.

[jpengar]

@sebdewet @AxelNennker It's ok with you if I close this PR after the split?

[RandyLevensalor]

I like the changes, but there seems to be a lot of capitalization of nouns, which are not proper nouns. I highlighted a few in this review, but didn't go through all of them.

[RandyLevensalor]

Suggested change

This document defines guidelines for the Operator's API Exposure Platform to manage CAMARA API access and when applicable, User Consent to comply with data protection requirements, and it introduces the formal concept of Purpose within an API invocation. Note that the document is predominantly based on concepts defined within GDPR regulations, however the proposed solution and concepts are generic and can by mapped to any relevant local data protection regulations.

This document defines guidelines for the operator's API exposure platform to manage CAMARA API access and when applicable, user consent to comply with data protection requirements, and it introduces the formal concept of purpose within an API invocation. Note that the document is predominantly based on concepts defined within GDPR regulations, however the proposed solution and concepts are generic and can by mapped to any relevant local data protection regulations.

Some of this capitalization doesn't seem necessary.

[eric-murray]

@RandyLevensalor
The capitalisation is intentional - it means the term has been defined elsewhere in the document (in this case, in the glossary section, though that itself is being updated in PR #212).

When capitalised in this way, it means the document is intentionally using the defined term, and this hopefully prevents others interpreting the term in a different way.

[jpengar]

Exactly, thanks @eric-murray. @RandyLevensalor As mentioned in #182 (comment), this PR #182 has been split into three PRs with the same changes for ease of handling. This PR should be closed and we can agree the necessary adjustments to the others.

[RandyLevensalor]

Suggested change

	- How Purpose applies to CAMARA APIs.
	- How purpose applies to CAMARA APIs.

Not sure why "Purpose" is capitalized.

[RandyLevensalor]

Suggested change

	- How to capture and store Consent when required, without materially degrading the End-User's experience of an ASP's Application.
	- How to capture and store consent when required, without materially degrading the End-User's experience of an ASP's Application.

Capitalization

[RandyLevensalor]

Suggested change

	- Policy enforcement to validate the existence and/or validity of Consent before authorizing access to a CAMARA API.
	- Policy enforcement to validate the existence and/or validity of consent before authorizing access to a CAMARA API.

[RandyLevensalor]

Suggested change

- `Aggregator`: the party that aggregates CAMARA APIs exposed by Operators, and exposes services that utilize these APIs to ASPs. An Aggregator can be a hyperscaler (e.g. Vonage, AWS, Azure, Google Cloud) offering its own services that consume CAMARA APIs, or exposing Operators' CAMARA APIs in an aggregated way, or an Operator acting as an Aggregator, i.e. an Operator aggregating other Operators' CAMARA APIs.

- `Aggregator`: the party that aggregates CAMARA APIs exposed by operators, and exposes services that utilize these APIs to ASPs. An aggregator can be a hyperscaler (e.g. Vonage, AWS, Azure, Google Cloud) offering its own services that consume CAMARA APIs, or exposing operators' CAMARA APIs in an aggregated way, or an operator acting as an aggregator, i.e. an operator aggregating other operators' CAMARA APIs.

[RandyLevensalor]

Suggested change

	- `API Exposure Platform`: the Operator's platform for exposing CAMARA APIs to ASPs and Aggregators, providing authentication and authorization mechanisms, and End-User Consent management. The API Exposure Platform typically consists of at least an Auth Server and an API Gateway.
	- `API Exposure Platform`: the Operator's platform for exposing CAMARA APIs to ASPs and aggregators, providing authentication and authorization mechanisms, and End-User consent management. The API exposure platform typically consists of at least an Auth Server and an API gateway.

[RandyLevensalor]

Suggested change

	- `Application Service Provider (ASP)`: the Legal Entity that provides the Application and/or services that consume CAMARA APIs.
	- `Application Service Provider (ASP)`: the legal entity that provides the application and/or services that consume CAMARA APIs.