In this message, I want to share the results of the ad hoc discussion we had after Thursday's formal call ended, and present options for going forward, along with a proposal. Please read and weigh in (even with a +1, if you agree...) by Tuesday if possible!)

Here's the relevant part of the notes:

====
271, 272: Add description fields to resource description doc and scope description doc: ... Resource description docs don't need I18N/L10N, but scope description documents might, for both a friendly name field and a description field. If we added a description field to scopes, then, do we want to make a breaking change and make this an array? Or leave the name as a default name that never changes and add an intl_name field or something like that? Or not care at all about I18N/L10N, but then possibly break things in future?
====

Here are the options I can think of. (Let me know if I missed any.)
  1. Do nothing. Others can always add their own extension for this.
  2. Add a "description" property for the resource description document only.
  3. Add a "description" property for the scope description document only.
  4. Add a "description" property for both the resource description document and the scope description document.
  5. (Not mutually exclusive with options 2, 3, or 4:) Add an internationalization/localization way for description values, likely modeled on the OIDC "claim request hash trick".
====

Here is my proposal: Option 1. Rationale:
  • A description field is pretty much a natural adjunct to a short name string. However, the interop cost is low if others add their own description fields. They might need multiple descriptions for different purposes. A display name seems like minimal bootstrapping, whereas descriptions may be gilding the lily.
  • I don't feel that strongly about it, however, and could be convinced by Option 2 or 4 (but I'm not crazy about Option 5, as detailed in the issue 269 email).

Eve Maler
Cell +1 425.345.6756 | Skype: xmlgrrl | Twitter: @xmlgrrl