Credential Offer section improvements
Nobody has claimed this yet.
- 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; orcredential_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_offerandcredential_offer_urimore 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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