<html><head><meta http-equiv="content-type" content="text/html; charset=utf-8"></head><body style="overflow-wrap: break-word; -webkit-nbsp-mode: space; line-break: after-white-space;">Hi all<div><br></div><div>I agree that making sure the status of documents is clear is important.</div><div><br></div><div>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.</div><div><br></div><div>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?</div><div><br></div><div>Thanks</div><div><br></div><div>Joseph</div><div><br><div><br><blockquote type="cite"><div>On 16 Mar 2023, at 04:58, Vittorio Bertocci via Openid-specs-ab <openid-specs-ab@lists.openid.net> wrote:</div><br class="Apple-interchange-newline"><div><div dir="ltr"><div>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.</div><div><br></div><div>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.</div><div>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 <a href="https://www.ietf.org/archive/id/draft-abr-twitter-reply-00.txt" target="_blank">https://www.ietf.org/archive/id/draft-abr-twitter-reply-00.txt</a> or <a href="https://datatracker.ietf.org/doc/draft-wkumari-not-a-draft/" target="_blank">https://datatracker.ietf.org/doc/draft-wkumari-not-a-draft/</a> shows that the problem is well known.</div><div>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.</div><div>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). </div><div><br></div><div>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. </div><div> </div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Wed, Mar 15, 2023 at 3:40 PM Mike Jones via Openid-specs-ab <<a href="mailto:openid-specs-ab@lists.openid.net" target="_blank">openid-specs-ab@lists.openid.net</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div>
<div lang="EN-US">
<div><p><strong>This message originated outside your organization.</strong></p><br>
<hr><br>
</div>
<div><p class="MsoNormal">(moving the working group to bcc in this reply)<u></u><u></u></p><p class="MsoNormal"><u></u> <u></u></p><p class="MsoNormal">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.<u></u><u></u></p><p class="MsoNormal"><u></u> <u></u></p><p class="MsoNormal">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
<a href="https://urldefense.com/v3/__https://openid.net/specs/openid-connect-prompt-create-1_0.html__;!!PwKahg!9W5WlhjMOV2d9VjN91HtI_AT6cZOB1dFMJcM3SchAw5CWVKZhMdRuTr7chn0pjxv7q0C5kCV2N_0jW5_xo0KYpK0IATPn3ViR3xL$" target="_blank">https://openid.net/specs/openid-connect-prompt-create-1_0.html</a>) and do not have a draft number. These same conventions are used by all working groups (c.f.
<a href="https://urldefense.com/v3/__https://openid.net/specs/fapi-2_0-security-02.html__;!!PwKahg!9W5WlhjMOV2d9VjN91HtI_AT6cZOB1dFMJcM3SchAw5CWVKZhMdRuTr7chn0pjxv7q0C5kCV2N_0jW5_xo0KYpK0IATPn4eIm8Oi$" target="_blank">https://openid.net/specs/fapi-2_0-security-02.html</a>).<u></u><u></u></p><p class="MsoNormal"><u></u> <u></u></p><p class="MsoNormal">Are there things we can do better? Yes. (We can discuss possibilities among the active editors.) Is there a crisis? No.<u></u><u></u></p><p class="MsoNormal"><u></u> <u></u></p><p class="MsoNormal">I stand behind the commendable work of our volunteer editors and thank them for their substantial contributions to the Foundation and the industry.<u></u><u></u></p><p class="MsoNormal"><u></u> <u></u></p><p class="MsoNormal"> Best wishes,<u></u><u></u></p><p class="MsoNormal"> -- Mike<u></u><u></u></p><p class="MsoNormal"><u></u> <u></u></p>
<div style="border-right:none;border-bottom:none;border-left:none;border-top:1pt solid rgb(225,225,225);padding:3pt 0in 0in"><p class="MsoNormal"><b>From:</b> Openid-specs-ab <<a href="mailto:openid-specs-ab-bounces@lists.openid.net" target="_blank">openid-specs-ab-bounces@lists.openid.net</a>>
<b>On Behalf Of </b>Nat Sakimura via Openid-specs-ab<br>
<b>Sent:</b> Wednesday, March 15, 2023 2:23 AM<br>
<b>To:</b> Artifact Binding/Connect Working Group <<a href="mailto:openid-specs-ab@lists.openid.net" target="_blank">openid-specs-ab@lists.openid.net</a>><br>
<b>Cc:</b> nat <nat@nat.consulting><br>
<b>Subject:</b> [Openid-specs-ab] Editors: Please rectify the drafts titles ASAP<u></u><u></u></p>
</div><p class="MsoNormal"><u></u> <u></u></p>
<div><p class="MsoNormal">I noticed that several of this WG's Drafts are not conforming to the practices the OIDF has been following. <u></u><u></u></p>
<div><p class="MsoNormal">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. <u></u><u></u></p>
</div>
<div>
<h2 style="margin-right:0in;margin-bottom:8.25pt;margin-left:0in;line-height:30pt;background:rgb(250,250,250)">
<span style="font-size:10pt;font-family:Helvetica,sans-serif;color:rgb(90,90,90)">Drafts</span><span style="font-family:Helvetica,sans-serif;color:rgb(90,90,90)"><u></u><u></u></span></h2><p class="MsoNormal" style="margin-left:54.75pt;line-height:16.5pt;background:rgb(250,250,250)">
<u></u><span style="font-size:10pt;font-family:Symbol;color:rgb(90,90,90)"><span>·<span style="font:7pt "Times New Roman"">
</span></span></span><u></u><span style="font-size:10.5pt;font-family:Helvetica,sans-serif;color:rgb(90,90,90)"><a href="https://urldefense.com/v3/__https://openid.net/specs/openid-connect-scim-profile-1_0.html__;!!PwKahg!9W5WlhjMOV2d9VjN91HtI_AT6cZOB1dFMJcM3SchAw5CWVKZhMdRuTr7chn0pjxv7q0C5kCV2N_0jW5_xo0KYpK0IATPnwOaIHYl$" target="_blank"><span style="color:rgb(247,140,64)">OpenID Connect Profile for SCIM Services</span></a> –
(Inactive) Defines how to use SCIM with OpenID Connect<u></u><u></u></span></p><p class="MsoNormal" style="margin-left:54.75pt;line-height:16.5pt;background:rgb(250,250,250)">
<u></u><span style="font-size:10pt;font-family:Symbol;color:rgb(90,90,90)"><span>·<span style="font:7pt "Times New Roman"">
</span></span></span><u></u><span style="font-size:10.5pt;font-family:Helvetica,sans-serif;color:rgb(90,90,90)"><a href="https://urldefense.com/v3/__https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html__;!!PwKahg!9W5WlhjMOV2d9VjN91HtI_AT6cZOB1dFMJcM3SchAw5CWVKZhMdRuTr7chn0pjxv7q0C5kCV2N_0jW5_xo0KYpK0IATPn6N8wiRP$" target="_blank"><span style="color:rgb(247,140,64)">OpenID for Verifiable Credential Issuance</span></a> –
This specification defines an API and corresponding OAuth-based authorization mechanisms for issuance of Verifiable Credentials<u></u><u></u></span></p><p class="MsoNormal" style="margin-left:54.75pt;line-height:16.5pt;background:rgb(250,250,250)">
<u></u><span style="font-size:10pt;font-family:Symbol;color:rgb(90,90,90)"><span>·<span style="font:7pt "Times New Roman"">
</span></span></span><u></u><span style="font-size:10.5pt;font-family:Helvetica,sans-serif;color:rgb(90,90,90)"><a href="https://urldefense.com/v3/__https://openid.net/specs/openid-connect-userinfo-vc-1_0.html__;!!PwKahg!9W5WlhjMOV2d9VjN91HtI_AT6cZOB1dFMJcM3SchAw5CWVKZhMdRuTr7chn0pjxv7q0C5kCV2N_0jW5_xo0KYpK0IATPn0ORANOt$" target="_blank"><span style="color:rgb(247,140,64)">OpenID Connect UserInfo Verifiable Credentials</span></a> –
Enables UserInfo responses as Verifiable Credentials<u></u><u></u></span></p>
<div>
<h2 style="margin-right:0in;margin-bottom:8.25pt;margin-left:0in;line-height:30pt;background:rgb(250,250,250)">
<span style="font-size:10pt;font-family:Helvetica,sans-serif;color:rgb(90,90,90)">Implementer’s Drafts</span><span style="font-family:Helvetica,sans-serif;color:rgb(90,90,90)"><u></u><u></u></span></h2><p class="MsoNormal" style="margin-left:54.75pt;line-height:16.5pt;background:rgb(250,250,250)">
<u></u><span style="font-size:10pt;font-family:Symbol;color:rgb(90,90,90)"><span>·<span style="font:7pt "Times New Roman"">
</span></span></span><u></u><span style="font-size:10.5pt;font-family:Helvetica,sans-serif;color:rgb(90,90,90)"><a href="https://urldefense.com/v3/__https://openid.net/specs/openid-connect-self-issued-v2-1_0.html__;!!PwKahg!9W5WlhjMOV2d9VjN91HtI_AT6cZOB1dFMJcM3SchAw5CWVKZhMdRuTr7chn0pjxv7q0C5kCV2N_0jW5_xo0KYpK0IATPn6-hPQ83$" target="_blank"><span style="color:rgb(247,140,64)">Self-Issued OpenID Provider V2</span></a> –
Enables End-users to use OpenID Providers (OPs) that they control [<a href="https://urldefense.com/v3/__https://openid.net/specs/openid-connect-self-issued-v2-1_0-ID1.html__;!!PwKahg!9W5WlhjMOV2d9VjN91HtI_AT6cZOB1dFMJcM3SchAw5CWVKZhMdRuTr7chn0pjxv7q0C5kCV2N_0jW5_xo0KYpK0IATPn2drxAe7$" target="_blank"><span style="color:rgb(247,140,64)">Most recent Implementer’s Draft</span></a>]<u></u><u></u></span></p><p class="MsoNormal" style="margin-left:54.75pt;line-height:16.5pt;background:rgb(250,250,250)">
<u></u><span style="font-size:10pt;font-family:Symbol;color:rgb(90,90,90)"><span>·<span style="font:7pt "Times New Roman"">
</span></span></span><u></u><span style="font-size:10.5pt;font-family:Helvetica,sans-serif;color:rgb(90,90,90)"><a href="https://urldefense.com/v3/__https://openid.net/specs/openid-4-verifiable-presentations-1_0.html__;!!PwKahg!9W5WlhjMOV2d9VjN91HtI_AT6cZOB1dFMJcM3SchAw5CWVKZhMdRuTr7chn0pjxv7q0C5kCV2N_0jW5_xo0KYpK0IATPn2naHffw$" target="_blank"><span style="color:rgb(247,140,64)">OpenID for Verifiable Presentations</span></a> –
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 [<a href="https://urldefense.com/v3/__https://openid.net/specs/openid-connect-4-verifiable-presentations-1_0-ID1.html__;!!PwKahg!9W5WlhjMOV2d9VjN91HtI_AT6cZOB1dFMJcM3SchAw5CWVKZhMdRuTr7chn0pjxv7q0C5kCV2N_0jW5_xo0KYpK0IATPnxqcx_oL$" target="_blank"><span style="color:rgb(247,140,64)">Most
recent Implementer’s Draft</span></a>]<u></u><u></u></span></p>
<div><p class="MsoNormal"><u></u> <u></u></p>
</div>
</div>
<div><p class="MsoNormal"><span style="font-size:10.5pt;font-family:Helvetica,sans-serif;color:rgb(90,90,90)">Note that these are OK regarding indicating their status on the title. They all have "draft" in their title. Thanks for following the practice. </span><u></u><u></u></p>
</div>
<div><p class="MsoNormal" style="margin-left:54.75pt;line-height:16.5pt;background:rgb(250,250,250)">
<u></u><span style="font-size:10pt;font-family:Symbol;color:rgb(90,90,90)"><span>·<span style="font:7pt "Times New Roman"">
</span></span></span><u></u><span style="font-size:10.5pt;font-family:Helvetica,sans-serif;color:rgb(90,90,90)"><a href="https://urldefense.com/v3/__https://openid.net/specs/openid-connect-claims-aggregation-1_0.html__;!!PwKahg!9W5WlhjMOV2d9VjN91HtI_AT6cZOB1dFMJcM3SchAw5CWVKZhMdRuTr7chn0pjxv7q0C5kCV2N_0jW5_xo0KYpK0IATPn_dxg-6r$" target="_blank"><span style="color:rgb(247,140,64)">OpenID Connect Claims Aggregation</span></a> –
Enables RPs to request and Claims Providers to return aggregated claims through OPs<u></u><u></u></span></p><p class="MsoNormal" style="margin-left:54.75pt;line-height:16.5pt;background:rgb(250,250,250)">
<u></u><span style="font-size:10pt;font-family:Symbol;color:rgb(90,90,90)"><span>·<span style="font:7pt "Times New Roman"">
</span></span></span><u></u><span style="font-size:10.5pt;font-family:Helvetica,sans-serif;color:rgb(90,90,90)"><a href="https://urldefense.com/v3/__https://openid.net/specs/openid-connect-federation-1_0.html__;!!PwKahg!9W5WlhjMOV2d9VjN91HtI_AT6cZOB1dFMJcM3SchAw5CWVKZhMdRuTr7chn0pjxv7q0C5kCV2N_0jW5_xo0KYpK0IATPnw5jDJW_$" target="_blank"><span style="color:rgb(247,140,64)">OpenID Connect Federation</span></a> – Defines how
sets of OPs and RPs can establish trust by utilizing a Federation Operator [<a href="https://urldefense.com/v3/__https://openid.net/specs/openid-connect-federation-1_0-ID3.html__;!!PwKahg!9W5WlhjMOV2d9VjN91HtI_AT6cZOB1dFMJcM3SchAw5CWVKZhMdRuTr7chn0pjxv7q0C5kCV2N_0jW5_xo0KYpK0IATPnw_6Ch18$" target="_blank"><span style="color:rgb(247,140,64)">Most recent Implementer’s Draft</span></a>]<u></u><u></u></span></p><p class="MsoNormal" style="margin-left:54.75pt;line-height:16.5pt;background:rgb(250,250,250)">
<u></u><span style="font-size:10pt;font-family:Symbol;color:rgb(90,90,90)"><span>·<span style="font:7pt "Times New Roman"">
</span></span></span><u></u><span style="font-size:10.5pt;font-family:Helvetica,sans-serif;color:rgb(90,90,90)"><a href="https://urldefense.com/v3/__https://openid.net/specs/openid-connect-native-sso-1_0.html__;!!PwKahg!9W5WlhjMOV2d9VjN91HtI_AT6cZOB1dFMJcM3SchAw5CWVKZhMdRuTr7chn0pjxv7q0C5kCV2N_0jW5_xo0KYpK0IATPn_zz3ivC$" target="_blank"><span style="color:rgb(247,140,64)">OpenID Connect Native SSO for Mobile Apps</span></a> –
Enables native applications by the same vendor to share login information [<a href="https://urldefense.com/v3/__https://openid.net/specs/openid-connect-native-sso-1_0-ID1.html__;!!PwKahg!9W5WlhjMOV2d9VjN91HtI_AT6cZOB1dFMJcM3SchAw5CWVKZhMdRuTr7chn0pjxv7q0C5kCV2N_0jW5_xo0KYpK0IATPn6sQxqjg$" target="_blank"><span style="color:rgb(247,140,64)">Most recent Implementer’s Draft</span></a>]<u></u><u></u></span></p>
</div>
<div><p class="MsoNormal">Best, <u></u><u></u></p>
</div><p class="MsoNormal"><span>-- </span><u></u><u></u></p>
<div>
<div><p class="MsoNormal">Nat Sakimura<u></u><u></u></p>
<div><p class="MsoNormal">OpenID AB/Connect WG Co-chair<u></u><u></u></p>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
_______________________________________________<br>
Openid-specs-ab mailing list<br>
<a href="mailto:Openid-specs-ab@lists.openid.net" target="_blank">Openid-specs-ab@lists.openid.net</a><br>
<a href="https://lists.openid.net/mailman/listinfo/openid-specs-ab" rel="noreferrer" target="_blank">https://lists.openid.net/mailman/listinfo/openid-specs-ab</a><br>
</div></blockquote></div></div>
_______________________________________________<br>Openid-specs-ab mailing list<br>Openid-specs-ab@lists.openid.net<br>https://lists.openid.net/mailman/listinfo/openid-specs-ab<br></div></blockquote></div><br></div></body></html>