openid / openid/OpenID4VCI

Credential Offer section improvements

Open
#255 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

clarification ready-for-PR
Dominant language
No language data
Stars
125
Forks
41
PR merge metrics
No merged PRs in 30d

Description

I am proposing to have another look at the Credential Offer section and consider the following changes to make it more concise and clearer.


The Credential Issuer passes the Credential Offer to the Wallet, by value or by reference, using HTTP GET request or an HTTP redirect to the Wallet's Credential Offer Endpoint defined in (#client-metadata).

The request must contain a single URI query parameter that is either:

  • credential_offer: Object with the Credential Offer parameters, which MUST NOT be present when credential_offer_uri parameter is present; or
  • credential_offer_uri: URI using the https scheme that references a resource containing a JSON object with the Credential Offer parameters. This MUST NOT be present when credential_offer parameter is present.

The motivation behind these changes is following:

  • In the original version the Credential Offer has more than one meaning and I would argue that we have a loop where Credential Offer contains a Credential Offer inside,
  • passed by reference rather than sent by reference,
  • URI is a type by itself, so explanation that is a string is redundant,
  • I changed URL to URI for consistency,
  • mentioning credential_offer and credential_offer_uri more than once is not needed,
  • other improvements for clarity

In addition to that I know that we already discussed how to express mutual exclusivity of these parameters, but please note that the current wording introduces redundancy by jointly using "single parameter", "either ... or", and "MUST NOT be present..." language. The "single parameter" + "either ... or" would be enough and would keep this section easier more concise and easier to understand. I encourage everyone to reconsider this option.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Review the Credential Offer section and its referenced client-metadata section in the specification, comparing the proposed wording with the current text. Done means adopting or resolving the requested concision, terminology, and mutual-exclusivity wording changes in that section.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.