fix: gender neutral editorials, closes https://github.com/openid/OpenID4VCI/issues/123 #143

peppelinux · 2023-12-09T16:01:06Z

This PR closes #123

Sakurann

thank you for doing the PR! the current text looks good.

I found one more occurrence of "her". Would it be possible to also fix a sentence in the first security considerations section
from

The Credential Issuer MAY want to ensure that private keys are properly protected from exfiltration and replay to prevent an adversary from impersonating the legitimate Credential holder by presenting her Credential.

to something like?

The Credential Issuer MAY want to ensure that private keys are properly protected from exfiltration and replay to prevent an adversary from impersonating the legitimate Credential holders by presenting their Credentials.

peppelinux · 2023-12-12T11:01:44Z

oh yes, done @Sakurann

openid-4-verifiable-credential-issuance-1_0.md

ju-cu · 2023-12-12T12:20:20Z

Missing pronouns:

Line #1675: Use Case: Credential Offer - Cross-Device (with Information Pre-Submitted by the End-User)
The End-User is starting a job at a new employer. An employer has requested the End-User to upload certain documents to the employee portal. A few days later, the End-User receives an email from the employer notifying her that the employee Credential is ready and asking her to scan a QR code to retrieve it. The End-User scans the QR code with her smartphone, which opens her Wallet. Meanwhile, the End-User has received a text message with a Transaction Code to her smartphone. After entering that Transaction Code in the Wallet for security reasons, the End-User confirms the Credential issuance, and receives Credential into the Wallet.

I believe, it does not matter whether or not the User receives the transaction code on the same smartphone, so I suggest to remove that part.

The End-User is starting a job at a new employer. An employer has requested the End-User to upload certain documents to the employee portal. A few days later, the End-User receives an email from the employer with a note that the employee Credential is ready. The email includes a QR code that the End-User should scan to retrieve the Credential.The End-User scans the QR code with a personal smartphone, which opens the Wallet. Meanwhile, the End-User received a text message with a Transaction Code. After entering that Transaction Code in the Wallet, the End-User confirms the Credential issuance, and receives the Credential into the Wallet.

ju-cu · 2023-12-12T12:31:52Z

Missing pronoun:

Line #1685: Wallet Initiated Issuance during Presentation
[...] The Wallet selects a Credential Issuer capable of issuing the lacking Credential and, upon End-User consent, sends the End-User to the Credential Issuer's End-User experience (Web site or app). Upon being authenticated and providing consent to issue the Credential into her Wallet, the End-User is sent back to the Wallet. The Wallet informs the End-User that Credential was successfully issued into the Wallet and is ready to be presented to the verifier app that originally requested presentation of that Credential.

"her Wallet" => "the Wallet"; Avoid duplicate wording at the beginning of a clause ("upon being authenticated").

[...] The Wallet selects a Credential Issuer capable of issuing the lacking Credential and, upon End-User consent, sends the End-User to the Credential Issuer's End-User experience (Web site or app). The Credential Issuer authenticates the End-User and the End-User provides the consent to issue the Credential to the Wallet. Then, the Credential Issuer sends the End-User back to the Wallet. The Wallet informs the End-User that the Credential was successfully issued into the Wallet and that it can now present it to the verifier app that originally requested the presentation of that Credential.

openid-4-verifiable-credential-issuance-1_0.md

tplooker

Minor editorial changes, but with those applied I'm happy to approve

Co-authored-by: Judith <[email protected]> Co-authored-by: Tobias Looker <[email protected]>

openid-4-verifiable-credential-issuance-1_0.md

@ju-cu

@ju-cu ^

openid-4-verifiable-credential-issuance-1_0.md

…into gender-neutral

selfissued

As I wrote in the corresponding issue, use of "they" to refer to a single person is grammatically incorrect. The correct way to not use "he" or "she" is to remove the pronouns entirely, replacing them with descriptive phrases like "the End-User".

Please do this. We should not knowingly introduce grammar errors into the specification.

peppelinux · 2023-12-13T22:13:20Z

openid-4-verifiable-credential-issuance-1_0.md

@@ -1668,27 +1668,27 @@ This is a non-exhaustive list of sample use cases.

 ## Credential Offer - Same-Device {#use-case-3}

-While browsing the university's home page, the End-User finds a link "request your digital diploma". The End-User clicks on this link and is being redirected to a digital Wallet. The Wallet notifies the End-User that a Credential Issuer offered to issue a diploma Credential. User confirms this inquiry and is taken to the university's Credential issuance service's End-User experience. After authenticating at the university and consenting to the issuance of a digital diploma, the End-User is sent back to the Wallet, where she can check the successful creation of the digital diploma.
+While browsing the university's home page, the End-User finds a link "request your digital diploma". The End-User clicks on this link and is being redirected to a digital Wallet. The Wallet notifies the End-User that a Credential Issuer offered to issue a diploma Credential. User confirms this inquiry and is taken to the university's Credential issuance service's End-User experience. Upon successful authentication at the university and consent to the issuance of a digital diploma, the End-User is redirected back to the Wallet. Here, the End-User can verify the successful creation of the digital diploma.


Suggested change

While browsing the university's home page, the End-User finds a link "request your digital diploma". The End-User clicks on this link and is being redirected to a digital Wallet. The Wallet notifies the End-User that a Credential Issuer offered to issue a diploma Credential. User confirms this inquiry and is taken to the university's Credential issuance service's End-User experience. Upon successful authentication at the university and consent to the issuance of a digital diploma, the End-User is redirected back to the Wallet. Here, the End-User can verify the successful creation of the digital diploma.

While browsing the university's home page, the End-User finds a link "request your digital diploma". The End-User clicks on this link and is being redirected to a digital Wallet. The Wallet notifies the End-User that a Credential Issuer offered to issue a diploma Credential. End-User confirms this inquiry and is taken to the university's Credential issuance service's End-User experience. Upon successful authentication at the university and consent to the issuance of a digital diploma, the End-User is redirected back to the Wallet. Here, the End-User can verify the successful creation of the digital diploma.

Sakurann · 2023-12-14T00:41:15Z

"they" to refer to a single person is grammatically incorrect.

I don't think this is incorrect anymore, or at least rapidly changing, with a lot of people choosing to use "they" as a pronoun pointing to an individual.
I agree we should probably use "end-user" wherever possible, but wanted to clarify that we are not doing that because it is grammatically incorrect.

peppelinux · 2023-12-14T08:32:51Z

I didn't attended the editor's call, and probably I don't know the details behind this discussion. I just want to say that I removed any "he/she/they" related to human subjects and I can continue doing this if you would kindly point me in the text where these pronouns are, if I miss some of them

peppelinux · 2023-12-14T08:37:05Z

openid-4-verifiable-credential-issuance-1_0.md

@@ -1250,7 +1250,7 @@ This specification also defines a new OAuth 2.0 Authorization Server metadata [@

 Credential Issuers often want to know what Wallet they are issuing Credentials to and how private keys are managed for the following reasons:


Suggested change

Credential Issuers often want to know what Wallet they are issuing Credentials to and how private keys are managed for the following reasons:

Credential Issuers needs to know the Wallet that is receiving the Credentials and the security measures in place for managing private keys, for the following reasons:

the original text honestly sounds ok..

peppelinux · 2023-12-14T08:39:58Z

openid-4-verifiable-credential-issuance-1_0.md

@@ -1250,7 +1250,7 @@ This specification also defines a new OAuth 2.0 Authorization Server metadata [@

 Credential Issuers often want to know what Wallet they are issuing Credentials to and how private keys are managed for the following reasons:

-* The Credential Issuer MAY want to ensure that private keys are properly protected from exfiltration and replay to prevent an adversary from impersonating the legitimate Credential holder by presenting her Credential.
+* The Credential Issuer MAY want to ensure that private keys are properly protected from exfiltration and replay to prevent an adversary from impersonating the legitimate Credential Holders by presenting their Credentials.


Suggested change

* The Credential Issuer MAY want to ensure that private keys are properly protected from exfiltration and replay to prevent an adversary from impersonating the legitimate Credential Holders by presenting their Credentials.

* The Credential Issuer MAY want to ensure that private keys are adequately protected against exfiltration and replay. This precaution helps prevent adversaries from impersonating legitimate Credential Holders and presenting the Credentials.

the original text is grammatically correct, too :).

I'm neutral, I only have tried to resolve the pending comments. If the authors agreed they may reject or merge this last suggestion, no worries.

peppelinux · 2023-12-14T08:41:18Z

@selfissued I have added some additional rewording in the desperate will to remove any concerning element. Please review

Sakurann · 2023-12-14T17:24:54Z

@selfissued can you please point to the specific instances of the usage of they that you are requesting changes?

selfissued

LGTM now - thanks

fix: gender neutral editorials

57e835f

peppelinux requested review from jogu, Sakurann, selfissued and ju-cu December 9, 2023 16:01

peppelinux mentioned this pull request Dec 9, 2023

Gender-neutral language #123

Closed

fix: gender neutral editorials - agreement -> consent

a24fc9d

Sakurann reviewed Dec 11, 2023

View reviewed changes

Sakurann requested review from danielfett and tlodderstedt December 11, 2023 19:35

fix: pending gender neutral editorials

be33560

ju-cu requested changes Dec 12, 2023

View reviewed changes

openid-4-verifiable-credential-issuance-1_0.md Outdated Show resolved Hide resolved

openid-4-verifiable-credential-issuance-1_0.md Outdated Show resolved Hide resolved

openid-4-verifiable-credential-issuance-1_0.md Outdated Show resolved Hide resolved

tplooker reviewed Dec 12, 2023

View reviewed changes

openid-4-verifiable-credential-issuance-1_0.md Outdated Show resolved Hide resolved

tplooker reviewed Dec 12, 2023

View reviewed changes

openid-4-verifiable-credential-issuance-1_0.md Outdated Show resolved Hide resolved

tplooker reviewed Dec 12, 2023

View reviewed changes

Apply suggestions from code review

a65b250

Co-authored-by: Judith <[email protected]> Co-authored-by: Tobias Looker <[email protected]>

ju-cu reviewed Dec 12, 2023

View reviewed changes

openid-4-verifiable-credential-issuance-1_0.md Outdated Show resolved Hide resolved

ju-cu approved these changes Dec 12, 2023

View reviewed changes

peppelinux commented Dec 12, 2023

View reviewed changes

openid-4-verifiable-credential-issuance-1_0.md Outdated Show resolved Hide resolved

Apply suggestions from code review

d7ed76c

@ju-cu ^

peppelinux commented Dec 12, 2023

View reviewed changes

openid-4-verifiable-credential-issuance-1_0.md Outdated Show resolved Hide resolved

peppelinux added 3 commits December 12, 2023 21:44

Apply suggestions from code review

1a707d3

editorial: holders -> Holders

5a6a839

Merge branch 'gender-neutral' of https://github.com/openid/OpenID4VCI …

7e78bb9

…into gender-neutral

Sakurann approved these changes Dec 13, 2023

View reviewed changes

tplooker approved these changes Dec 13, 2023

View reviewed changes

selfissued requested changes Dec 13, 2023

View reviewed changes

peppelinux commented Dec 13, 2023

View reviewed changes

peppelinux commented Dec 14, 2023

View reviewed changes

Sakurann requested a review from selfissued December 14, 2023 17:25

selfissued approved these changes Dec 16, 2023

View reviewed changes

Sakurann merged commit 06c2d06 into main Dec 18, 2023
2 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix: gender neutral editorials, closes https://github.com/openid/OpenID4VCI/issues/123 #143

fix: gender neutral editorials, closes https://github.com/openid/OpenID4VCI/issues/123 #143

peppelinux commented Dec 9, 2023 •

edited by tplooker

Loading

Sakurann left a comment

peppelinux commented Dec 12, 2023

ju-cu commented Dec 12, 2023

ju-cu commented Dec 12, 2023

tplooker left a comment

selfissued left a comment

peppelinux Dec 13, 2023

Sakurann commented Dec 14, 2023

peppelinux commented Dec 14, 2023

peppelinux Dec 14, 2023

Sakurann Dec 14, 2023

peppelinux Dec 14, 2023

Sakurann Dec 14, 2023

peppelinux Dec 14, 2023

peppelinux commented Dec 14, 2023

Sakurann commented Dec 14, 2023

selfissued left a comment

		@@ -1250,7 +1250,7 @@ This specification also defines a new OAuth 2.0 Authorization Server metadata [@

		Credential Issuers often want to know what Wallet they are issuing Credentials to and how private keys are managed for the following reasons:

	Credential Issuers often want to know what Wallet they are issuing Credentials to and how private keys are managed for the following reasons:
	Credential Issuers needs to know the Wallet that is receiving the Credentials and the security measures in place for managing private keys, for the following reasons:

	* The Credential Issuer MAY want to ensure that private keys are properly protected from exfiltration and replay to prevent an adversary from impersonating the legitimate Credential Holders by presenting their Credentials.
	* The Credential Issuer MAY want to ensure that private keys are adequately protected against exfiltration and replay. This precaution helps prevent adversaries from impersonating legitimate Credential Holders and presenting the Credentials.

fix: gender neutral editorials, closes https://github.com/openid/OpenID4VCI/issues/123 #143

fix: gender neutral editorials, closes https://github.com/openid/OpenID4VCI/issues/123 #143

Conversation

peppelinux commented Dec 9, 2023 • edited by tplooker Loading

Sakurann left a comment

Choose a reason for hiding this comment

peppelinux commented Dec 12, 2023

ju-cu commented Dec 12, 2023

ju-cu commented Dec 12, 2023

tplooker left a comment

Choose a reason for hiding this comment

selfissued left a comment

Choose a reason for hiding this comment

peppelinux Dec 13, 2023

Choose a reason for hiding this comment

Sakurann commented Dec 14, 2023

peppelinux commented Dec 14, 2023

peppelinux Dec 14, 2023

Choose a reason for hiding this comment

Sakurann Dec 14, 2023

Choose a reason for hiding this comment

peppelinux Dec 14, 2023

Choose a reason for hiding this comment

Sakurann Dec 14, 2023

Choose a reason for hiding this comment

peppelinux Dec 14, 2023

Choose a reason for hiding this comment

peppelinux commented Dec 14, 2023

Sakurann commented Dec 14, 2023

selfissued left a comment

Choose a reason for hiding this comment

peppelinux commented Dec 9, 2023 •

edited by tplooker

Loading