Question: Why is there no useful diagrams in the spec/standard?

[furikake]

I'm new to the CDR standard and find it incredibly difficult to understand without some simple diagrams. If you look at standards like OAuth 2.0, OpenID Connect and even TDIF, they all start with a context diagram to aid readers and include additional diagrams when necessary. There are two state diagrams in the standard so it is not devoid of imagery.

Example from OpenID Connect Core 1.0 (https://openid.net/specs/openid-connect-core-1_0.html#Overview)

+--------+                                   +--------+
|        |                                   |        |
|        |---------(1) AuthN Request-------->|        |
|        |                                   |        |
|        |  +--------+                       |        |
|        |  |        |                       |        |
|        |  |  End-  |<--(2) AuthN & AuthZ-->|        |
|        |  |  User  |                       |        |
|   RP   |  |        |                       |   OP   |
|        |  +--------+                       |        |
|        |                                   |        |
|        |<--------(3) AuthN Response--------|        |
|        |                                   |        |
|        |---------(4) UserInfo Request----->|        |
|        |                                   |        |
|        |<--------(5) UserInfo Response-----|        |
|        |                                   |        |
+--------+                                   +--------+

Example from OAuth 2.0 (https://datatracker.ietf.org/doc/html/rfc6749#section-4.2)

     +----------+
     | Resource |
     |  Owner   |
     |          |
     +----------+
          ^
          |
         (B)
     +----|-----+          Client Identifier     +---------------+
     |         -+----(A)-- & Redirection URI --->|               |
     |  User-   |                                | Authorization |
     |  Agent  -|----(B)-- User authenticates -->|     Server    |
     |          |                                |               |
     |          |<---(C)--- Redirection URI ----<|               |
     |          |          with Access Token     +---------------+
     |          |            in Fragment
     |          |                                +---------------+
     |          |----(D)--- Redirection URI ---->|   Web-Hosted  |
     |          |          without Fragment      |     Client    |
     |          |                                |    Resource   |
     |     (F)  |<---(E)------- Script ---------<|               |
     |          |                                +---------------+
     +-|--------+
       |    |
      (A)  (G) Access Token
       |    |
       ^    v
     +---------+
     |         |
     |  Client |
     |         |
     +---------+

It wasn't until I started looking at the CDR Register documentation (https://cdr-register.github.io/register-staging/) that it made more sense due to the component and sequence diagrams.

Did I just start reading at the wrong level? Is there supposed to be an over overarching site that pieces it all together?

[CDR-API-Stream]

Hi @furikake and welcome to the CDR. There are a couple of responses to your question:

1. We have produced diagrams at various points but, as the standards are legally binding, we have found that including diagrams directly in the standards can create ambiguity from an interpretation perspective
2. We are aware that this does create problems with understanding the ecosystem (we've been told this before) and we seek to address this via our support portal. This is where we post clarification and guidance articles and field general questions. If you go there and search the articles you will find useful information that may assist
3. We have been planning to develop an implementation guide as a companion to the CDR standards that would contain this content but we have not yet progressed to a point where we are ready to publish

In addition, this repo is used for more formal consultations of changes to the standards. It is preferred if you could raise questions on the support portal or, if you have suggestions for change, raise them as change requests, on our standards maintenance repository at: https://github.com/ConsumerDataStandardsAustralia/standards-maintenance

Please feel free to contribute and help us make the CDR better.