[federation] please add a visual diagram

[Kristina Yasuda]

the spec has become very huge and takes a lot of time to understand for newcomers. Please consider adding an ASCII diagram of the relationship between Entity Statements and Entity Configurations, Trust Chain and Trust Mark, Leaf Entity and Trust Anchor, etc. There is a lot of similar terminology and I often get confused. I try to go back to the “Overall architecture“ section, but it still takes me time to visualize and consume..

[Kristina Yasuda]

I see a sequence diagram here but would be good to have it much earlier in the spec too IMO. https://openid.bitbucket.io/connect/openid-connect-federation-1_0.html#section-8.1

[Michael Jones]

We discussed this on the 4-Aug-23 Federation Editors' call. We agree that additional diagrams could help reader comprehension.

We could possibly whiteboard diagrams together at OSW later this month.

[Giuseppe De Marco]

                                                                                                                  +---------------------------------------+      
                                                                                                                  |   TRUST CHAIN                         |      
                                                           +-----------------------------------+                  | +-----------------------------------+ |      
       +-------------------+                               |                                   |                  | |                                   | |      
       |                   |                               |    ENTITY CONFIGURATION           |                  | |   ENTITY STATEMENT                | |      
       |   TRUST ANCHOR    | .well-known/openid-federation |                                   | FETCH ENDPOINT   | |                                   | |      
       |                   |-------------------------------|    - FEDERATION ENTITY KEYS       |-------------------->   - FEDERATION ENTITY KEYS        | |      
       +---------^---------+                               |    - METADATA                     |                  | |   - METADATA POLICY               | |      
                 |                                         |    - CONSTRAINTS                  |                  | |   - METADATA                      | |      
                 |                                         |                                   |                  | |                                   | |      
                 |                                         +-----------------------------------+                  | +-----------------|-----------------+ |      
                 |                                                                                                |                   |                   |      
                 |                                                                                                |                   |                   |      
                 |                                         +-----------------------------------+                  | +-----------------v-----------------+ |      
                 |                                         |                                   |                  | |                                   | |      
       +---------v---------+                               |    ENTITY CONFIGURATION           |                  | |   ENTITY STATEMENT                | |      
       |                   | .well-known/openid-federation |                                   | FETCH ENDPOINT   | |                                   | |      
       |  INTERMEDIATE     |-------------------------------|    - FEDERATION ENTITY KEYS       |-------------------->   - FEDERATION ENTITY KEYS        | |      
       |                   |                               |    - METADATA                     |                  | |   - METADATA POLICY               | |      
       +---------^---------+                               |    - TRUST MARKS                  |                  | |   - METADATA                      | |      
                 |                                         |                                   |                  | |                                   | |      
                 |                                         +-----------------------------------+                  | +-----------------|-----------------+ |      
                 |                                                                                                |                   |                   |      
                 |                                                                                                |                   |                   |      
                 |                                                                                                | +-----------------------------------+ |      
                 |                                                                                                | |                                   | |      
                 |                                                                                                | |   ENTITY CONFIGURATION            | |      
                 |                                                                                                | |                                   | |      
       +---------v--------+                                                                                       | |   - FEDERATION ENTITY KEYS        | |      
       |                  | .well-known/openid-federation                                                         | |   - METADATA                      | |      
       |  LEAF            |---------------------------------------------------------------------------------------|>|   - TRUST MARKS                   | |      
       |                  |                                                                                       | |                                   | |      
       +------------------+                                                                                       | +-----------------------------------+ |      
                                                                                                                  +---------------------------------------+      

just for fun

[Giuseppe De Marco]

@Kristina Yasuda
Are the “drawing” I have shared in the previous comment or the sequence diagram that we already have in the specs, here, good enough?

for the first one:
we can improve it and then have it in a form of a PR, so please feel free to give your impressions/comment.

for the second one:
are you more interested instead in a diagram within the introductory section?
or, differently, do you think that would be better to move the seq diagram we already have in the section 8.1 to the introductory sections?

[Kristina Yasuda]

Hi Giuseppe, I think the visual above looks great. maybe add that leaf/intermediate/trust anchor on the left refers to their identifieres?

[Michael Jones]

As discussed on the 7-Sep-23 working group call, we would like to include such a diagram in the upcoming Implementer’s Draft.

[Giuseppe De Marco]

PR Done here https://bitbucket.org/openid/connect/pull-requests/616 for your kindly revision

[Michael Jones]

Addressed by https://bitbucket.org/openid/connect/pull-requests/616