openid / openid/OpenID4VP

Document structure

Open
#603 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Shell
Stars
112
Forks
38
Avg merge
12d 19h
Merged PRs (30d)
4

Description

The document structure is somewhat misleading and/or not initially clear to a reader. As examples, I can name the following:

  • Section "3. Overview" mentions the cross-device flows having one additional step involving the request_uri. Although this is defined in RFC 9101, this is not mentioned in any section of "5. Authorization Request".
  • Section "5. Authorization Request" seems to start with the changes to RFC6749, then goes on to a feature, followed by example authorization requests. This is followed by many subpoints referenced in Sections "5.1. New Parameters" and "5.2. Existing Parameters". While this is not wrong content-wise, it does not provide the table of contents (toc) with an adequate overview of the specification hierarchy. Maybe consider sections 5.3 through 5.11 as subsubsections.
  • Further on this topic, sections "6. Digital Credentials Query Language (DCQL)" and "7. Claims Path Pointer" are further examples of sections being dependencies and placed in an unusual TOC location. Maybe section 6 deserves to be its own section, giving its importance and novelty to this specification, but does the same apply to claims path pointers? In particular, section "7.5. DCQL Examples" seems out of place and wrongly named and confusingly placed (plural examples for a single example; section "7.4. DCQL examples" is not a subsection of "6. Digital Credentials Query Language (DCQL)"?

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

Start by reviewing the table of contents and Sections 3, 5, 6, and 7, including Sections 5.1–5.11 and the DCQL examples. Map the dependencies and examples against the surrounding specification text, then propose a hierarchy and naming that makes the structure and cross-references clear. Done means the TOC accurately reflects the organization and the cited sections no longer appear misplaced or ambiguously numbered.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.