[Openid-specs-ab] Version control of OIDF documents (Used to be "Editors: Please rectify the drafts titles ASAP")

Kristina Yasuda Kristina.Yasuda at microsoft.com
Thu Mar 16 23:46:26 UTC 2023 

(Changing the subject of an email to a more general one)
(I agree that this is a OIDF-wide problem and that this is not the most appropriate ML, but couldn’t find a better ML, so decided to send this note here in hopes that this, hopefully constructive, input is taken to a right venue to be acted upon.)

I think, at the higher-level, version control of the specifications in OIDF can be significantly improved.

I have been receiving feedback from those not familiar with OIDF that a) it is hard to understand what is the difference between the documents at openid.bitbucket.io and openid.net and that b) it is hard to find past Implementer’s Drafts. I understand that there is a page at openid.net that lists them all, but usually people start at the URL to a specification they are interested in.

So one suggestion I’ve been wanting to make for a while is that every single OIDF spec should say “Editor’s draft can be found at https://openid.bitbucket.io... . WG’s draft can be found at https://openid.net/... . First/Second/Third Implementer’s draft can be found at … . ” followed by an explanation or a pointer to an explanation of what is Editor’s draft and what is WG’s draft and what is an Implementer’s draft. This is different from previously mentioned “Warning” section.

I also think every single OIDF spec should use the same convention for the URLs. Some use <spec-name>-1.0-ver, some use <spec-name>-1.0, some use <spec-name>-ver.

I have previously received a question if there is a template from someone who wanted to contribute to OID, so having one might help. But in the short term, I think it will be more useful to document “the practices the OIDF has been following” which will probably result in a list of clear requirements on what information each specification should have in the draft at the minimum, such as putting a draft number in the draft title.

Earlier OIDF specs/drafts have one format, more recent ones have different formats, and I believe for good reasons. For example, one of the newer formats is friendlier to generate xml/html files and makes it easier to set up pipelines to auto generate htmls and auto publish editor’s drafts – something ekyc-ida wg has done and what Mark has been helping me to do for OID4VC specs. So having one template to rule them all would take much longer than having a set of requirements, since I am also sure there will be strong opinions around IETF format, ISO format, OIDF format, etc.

Finally, I would like to note that editors of OIDF documents are acting in good faith and would not intentionally portray draft documents as published standards.

Thank you,
Kristina



From: Openid-specs-ab <openid-specs-ab-bounces at lists.openid.net> On Behalf Of Joseph Heenan via Openid-specs-ab
Sent: Thursday, March 16, 2023 3:24 AM
To: Artifact Binding/Connect Working Group <openid-specs-ab at lists.openid.net>
Cc: Joseph Heenan <joseph at authlete.com>
Subject: Re: [Openid-specs-ab] Editors: Please rectify the drafts titles ASAP

Hi all

I agree that making sure the status of documents is clear is important.

I suspect one thing we could do to help would be to have a template for specs that has all the things like ‘draft’ markings already in place.

Are there any good examples of specs (in the markdown format we now tend to use for new specs) that generate html that are all correctly marked as draft etc?

Thanks

Joseph



On 16 Mar 2023, at 04:58, Vittorio Bertocci via Openid-specs-ab <openid-specs-ab at lists.openid.net<mailto:openid-specs-ab at lists.openid.net>> wrote:

While joining you in your praise for the work our volunteer editors do, and without getting into the details of whether there is formal guidance about formatting, I think the problem "specs still subject to change might be perceived as official standards" Nat raises is specific, important and worth considering, without finger pointing but with a desire to better serve our community.

IMO specifications shouldn't be intelligence or knowledge tests, but strive to achieve maximum clarity- especially for aspects that are already known to be poorly understood by the general readership.
Looking at the industry in general, the use of docs naming schema is a notoriously poor way of expressing whether a spec is authoritative, a work in progress or literally just a proposal. The existence of things like https://www.ietf.org/archive/id/draft-abr-twitter-reply-00.txt or https://datatracker.ietf.org/doc/draft-wkumari-not-a-draft/ shows that the problem is well known.
Requiring that draft specs carry forward in new drafts the Warning section or equivalent doesn't seem particularly onerous, given that we already expect every spec to have the Copyright notice & License section- it's literally the same cut & paste gesture as they are both adjacent and 100% boilerplate.
Moreover, the fact that some drafts do have a Warning section offers further ground for people to expect that the drafts without it aren't subject to the same limitation (eg they are stable).

I agree this isn't a "drop everything and fix it" problem, but it also shouldn't sleep on it IMO... so that no one can accuse us of cultivating the perception of stability for things that aren't yet stable.


On Wed, Mar 15, 2023 at 3:40 PM Mike Jones via Openid-specs-ab <openid-specs-ab at lists.openid.net<mailto:openid-specs-ab at lists.openid.net>> wrote:

This message originated outside your organization.

________________________________

(moving the working group to bcc in this reply)

Nat, while I know that your intentions are good, I believe that I have to correct the impression your message gives that the editors of our specs have not been following OpenID Foundation spec formatting rules.  I’m writing this reply in my capacity as OpenID Board Secretary – where one of my roles is to ensure that our published specifications follow OpenID Foundation practices.

I’m not going to go into every detail on this working group thread, as this is really a discussion that should happen among the active editors across the active working groups (which is why I moved this WG to bcc).  But I believe we’ve done a good job ensuring that the differences between drafts and Final Specifications are clear.  Drafts include the word “Draft” or “Internet-Draft” in the draft headings and/or title and have a draft number.   (The different placement of these status indicators largely has to do with different tooling, with xml2rfc v1, v2, and v3 all treating headers somewhat differently and the multiple Markdown toolchains we use likewise having differences.) Final specifications likewise use the word “Final” (for instance, see https://openid.net/specs/openid-connect-prompt-create-1_0.html<https://urldefense.com/v3/__https://openid.net/specs/openid-connect-prompt-create-1_0.html__;!!PwKahg!9W5WlhjMOV2d9VjN91HtI_AT6cZOB1dFMJcM3SchAw5CWVKZhMdRuTr7chn0pjxv7q0C5kCV2N_0jW5_xo0KYpK0IATPn3ViR3xL$>) and do not have a draft number.  These same conventions are used by all working groups (c.f. https://openid.net/specs/fapi-2_0-security-02.html<https://urldefense.com/v3/__https://openid.net/specs/fapi-2_0-security-02.html__;!!PwKahg!9W5WlhjMOV2d9VjN91HtI_AT6cZOB1dFMJcM3SchAw5CWVKZhMdRuTr7chn0pjxv7q0C5kCV2N_0jW5_xo0KYpK0IATPn4eIm8Oi$>).

Are there things we can do better?  Yes.  (We can discuss possibilities among the active editors.)  Is there a crisis?  No.

I stand behind the commendable work of our volunteer editors and thank them for their substantial contributions to the Foundation and the industry.

                                                       Best wishes,
                                                       -- Mike

From: Openid-specs-ab <openid-specs-ab-bounces at lists.openid.net<mailto:openid-specs-ab-bounces at lists.openid.net>> On Behalf Of Nat Sakimura via Openid-specs-ab
Sent: Wednesday, March 15, 2023 2:23 AM
To: Artifact Binding/Connect Working Group <openid-specs-ab at lists.openid.net<mailto:openid-specs-ab at lists.openid.net>>
Cc: nat <nat at nat.consulting<mailto:nat at nat.consulting>>
Subject: [Openid-specs-ab] Editors: Please rectify the drafts titles ASAP

I noticed that several of this WG's Drafts are not conforming to the practices the OIDF has been following.
Specifically, these drafts and implementer's drafts do not indicate their status in their titles. Unfortunately, they also lack the "Status of this memo" or "Warning" section that indicates that they are drafts and subject to change. This makes them appear as if they are published standards. They should be rectified ASAP.
Drafts
•        OpenID Connect Profile for SCIM Services<https://urldefense.com/v3/__https://openid.net/specs/openid-connect-scim-profile-1_0.html__;!!PwKahg!9W5WlhjMOV2d9VjN91HtI_AT6cZOB1dFMJcM3SchAw5CWVKZhMdRuTr7chn0pjxv7q0C5kCV2N_0jW5_xo0KYpK0IATPnwOaIHYl$> – (Inactive) Defines how to use SCIM with OpenID Connect
•        OpenID for Verifiable Credential Issuance<https://urldefense.com/v3/__https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html__;!!PwKahg!9W5WlhjMOV2d9VjN91HtI_AT6cZOB1dFMJcM3SchAw5CWVKZhMdRuTr7chn0pjxv7q0C5kCV2N_0jW5_xo0KYpK0IATPn6N8wiRP$> – This specification defines an API and corresponding OAuth-based authorization mechanisms for issuance of Verifiable Credentials
•        OpenID Connect UserInfo Verifiable Credentials<https://urldefense.com/v3/__https://openid.net/specs/openid-connect-userinfo-vc-1_0.html__;!!PwKahg!9W5WlhjMOV2d9VjN91HtI_AT6cZOB1dFMJcM3SchAw5CWVKZhMdRuTr7chn0pjxv7q0C5kCV2N_0jW5_xo0KYpK0IATPn0ORANOt$> – Enables UserInfo responses as Verifiable Credentials
Implementer’s Drafts
•        Self-Issued OpenID Provider V2<https://urldefense.com/v3/__https://openid.net/specs/openid-connect-self-issued-v2-1_0.html__;!!PwKahg!9W5WlhjMOV2d9VjN91HtI_AT6cZOB1dFMJcM3SchAw5CWVKZhMdRuTr7chn0pjxv7q0C5kCV2N_0jW5_xo0KYpK0IATPn6-hPQ83$> – Enables End-users to use OpenID Providers (OPs) that they control [Most recent Implementer’s Draft<https://urldefense.com/v3/__https://openid.net/specs/openid-connect-self-issued-v2-1_0-ID1.html__;!!PwKahg!9W5WlhjMOV2d9VjN91HtI_AT6cZOB1dFMJcM3SchAw5CWVKZhMdRuTr7chn0pjxv7q0C5kCV2N_0jW5_xo0KYpK0IATPn2drxAe7$>]
•        OpenID for Verifiable Presentations<https://urldefense.com/v3/__https://openid.net/specs/openid-4-verifiable-presentations-1_0.html__;!!PwKahg!9W5WlhjMOV2d9VjN91HtI_AT6cZOB1dFMJcM3SchAw5CWVKZhMdRuTr7chn0pjxv7q0C5kCV2N_0jW5_xo0KYpK0IATPn2naHffw$> – This specification defines a mechanism on top of OAuth 2.0 to allow the presentation of claims in the form of verifiable credentials as part of the protocol flow [Most recent Implementer’s Draft<https://urldefense.com/v3/__https://openid.net/specs/openid-connect-4-verifiable-presentations-1_0-ID1.html__;!!PwKahg!9W5WlhjMOV2d9VjN91HtI_AT6cZOB1dFMJcM3SchAw5CWVKZhMdRuTr7chn0pjxv7q0C5kCV2N_0jW5_xo0KYpK0IATPnxqcx_oL$>]

Note that these are OK regarding indicating their status on the title. They all have "draft" in their title. Thanks for following the practice.
•        OpenID Connect Claims Aggregation<https://urldefense.com/v3/__https://openid.net/specs/openid-connect-claims-aggregation-1_0.html__;!!PwKahg!9W5WlhjMOV2d9VjN91HtI_AT6cZOB1dFMJcM3SchAw5CWVKZhMdRuTr7chn0pjxv7q0C5kCV2N_0jW5_xo0KYpK0IATPn_dxg-6r$> – Enables RPs to request and Claims Providers to return aggregated claims through OPs
•        OpenID Connect Federation<https://urldefense.com/v3/__https://openid.net/specs/openid-connect-federation-1_0.html__;!!PwKahg!9W5WlhjMOV2d9VjN91HtI_AT6cZOB1dFMJcM3SchAw5CWVKZhMdRuTr7chn0pjxv7q0C5kCV2N_0jW5_xo0KYpK0IATPnw5jDJW_$> – Defines how sets of OPs and RPs can establish trust by utilizing a Federation Operator [Most recent Implementer’s Draft<https://urldefense.com/v3/__https://openid.net/specs/openid-connect-federation-1_0-ID3.html__;!!PwKahg!9W5WlhjMOV2d9VjN91HtI_AT6cZOB1dFMJcM3SchAw5CWVKZhMdRuTr7chn0pjxv7q0C5kCV2N_0jW5_xo0KYpK0IATPnw_6Ch18$>]
•        OpenID Connect Native SSO for Mobile Apps<https://urldefense.com/v3/__https://openid.net/specs/openid-connect-native-sso-1_0.html__;!!PwKahg!9W5WlhjMOV2d9VjN91HtI_AT6cZOB1dFMJcM3SchAw5CWVKZhMdRuTr7chn0pjxv7q0C5kCV2N_0jW5_xo0KYpK0IATPn_zz3ivC$> – Enables native applications by the same vendor to share login information [Most recent Implementer’s Draft<https://urldefense.com/v3/__https://openid.net/specs/openid-connect-native-sso-1_0-ID1.html__;!!PwKahg!9W5WlhjMOV2d9VjN91HtI_AT6cZOB1dFMJcM3SchAw5CWVKZhMdRuTr7chn0pjxv7q0C5kCV2N_0jW5_xo0KYpK0IATPn6sQxqjg$>]
Best,
--
Nat Sakimura
OpenID AB/Connect WG Co-chair
_______________________________________________
Openid-specs-ab mailing list
Openid-specs-ab at lists.openid.net<mailto:Openid-specs-ab at lists.openid.net>
https://lists.openid.net/mailman/listinfo/openid-specs-ab
_______________________________________________
Openid-specs-ab mailing list
Openid-specs-ab at lists.openid.net<mailto:Openid-specs-ab at lists.openid.net>
https://lists.openid.net/mailman/listinfo/openid-specs-ab

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openid.net/pipermail/openid-specs-ab/attachments/20230316/b150a701/attachment-0001.html>

More information about the Openid-specs-ab mailing list