Skip to content

Document structure #603

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
101Coder101 opened this issue May 13, 2025 · 0 comments
Open

Document structure #603

101Coder101 opened this issue May 13, 2025 · 0 comments

Comments

@101Coder101
Copy link

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)"?
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant