Use singular form instead of plural form

[msporny]

During the W3C Credentials Community Group presentation, I noticed that the schema switches between singular and plural form for the attribute names.

https://identity.foundation/credential-schemas/#basic-person-abstract-data-model

The current best practice is to use singular form everywhere, especially for the term URLs. The reasoning being that plural looks strange when you only have one entry, which is often... and they look especially strange when expressed in any sort of triple/quad expression (e.g., NQuads), and the English rules for pluralization are not straightforward for non-English speakers.

Ultimately, it's an easy rule to apply everywhere -- just use singular form for attribute names.

[ottomorac]

Hi @msporny thanks for the feedback.

Just to clarify; Does this apply to all attributes including arrays? For example see a few of the attributes in the main basic person data model:

• issuanceDate - single
• expirationDate - single
• names (array) - plural
• addresses (array) - plural

The "names" array contains one or more "name" objects ( https://identity.foundation/credential-schemas/#name-object)

The "addresses" array contains one or more "address" objects ( https://identity.foundation/credential-schemas/#address-object )

To me, using the plural refers to the array field in the main data model, and using the single refers to the single object. However happy to take feedback if folks at W3C do it differently than this. Thanks!

[msporny]

Does this apply to all attributes including arrays?

Yes, it does.

To me, using the plural refers to the array field in the main data model, and using the single refers to the single object.

Yes, understood, however, some people tend to get confused when you say: "names" and then have an array with only one value. So, we've found it useful to be consistent and either always use plural form (which doesn't work, because many values are singular), or always use singular form (where if there is an array with multiple values associated with the property, it becomes obvious that there can be more than one value in there.

Remember that some of these vocabulary items will result in the generation of RDF statements at some point, where you end up with something like this if you use plural form for the terms:

<person234> names "Bob";
<person234> names "Bobby";

... which feels slightly off, because those are singular data statements (one per name value) vs. this when you use singular terms:

<person234> name "Bob";
<person234> name "Bobby";

It's not a huge thing, but we have gone around and around in the WGs on this over the past decade and ended up with singular form everywhere. My suggestion is to use singular form everywhere, and arrays when there can be more than one value. That's how we model the vocabularies at W3C.

[kimdhamilton]

Let's explore whether this results in mismatches with terms of other comparison points. At minimum, we'll need to pick & document what we use. Then we could provide "crosswalk" guidance for different contexts.

Look through IANA media types for OpenID

[amcfield]

Hi Manu, I get the reasoning (& personally don't really have a preference either way) - but I've done some work on OIDF for Identity Assurance, and that spec uses 'nationalities' for instance, with an array (although most people would only have one).
This would map to 'nationalities' in DIF basic person, and may look a little odd if it mapped to a 'nationality' array.

https://openid.net/specs/openid-connect-4-ida-claims-1_0.html

OIDC itself only uses a 'flat' structure with singular values for everything except name (given, nickname, preferred), which are listed without any array at the top level. This could lead to a mismatch between 'name' in OIDC (singular value) and 'name' in DIF BPS (if singular version is used to name the array). We'd need to be clear that OIDC 'name' maps to 'name.legalName' in DIF and not to the array itself.

[msporny]

OIDC itself only uses a 'flat' structure with singular values for everything

Yes, which is quite unfortunate, as our experience is that information in credentials often do not have a flat structure (especially when you start combining credential data about the same individual).

This could lead to a mismatch between 'name' in OIDC

Yes, and to put a finer point on how different information models fail to capture properties like "name" properly, see "Falsehoods Programmers Believe About Names":

https://www.kalzumeus.com/2010/06/17/falsehoods-programmers-believe-about-names/

No one said data modelling was easy. :P

[kimdhamilton]

Discussion on Dec 3, 2024 call:

• Preference for singular form, for reasons discussed in this thread
• Additional validation comes from schema.org's bulk change from plural to singular, referenced in this issue: Remove "legacy" wording, now that site navigation handles supercededBy directly schemaorg/schemaorg#153