API design should emphasize that sites should request minimal properties, not full identity documents

[npdoty]

It might sound a little like bike-shedding, but I am concerned in seeing API methods called requestIdentity, as it seems to suggest that what you will get back is the user's complete identity.

If successfully, responsibly deployed, the vast majority of uses of this API should return responses with particular properties or claims or proofs from a credential, but not what the developer might think of as the user's identity.

How can we design an API that makes it clear that sites should ask for only what they need, and not over-ask?

(this is for dc2-proposal but I don't have label permission)

[aniltj]

Bit old school, but requestAttributes or requestAttributeBundle ?

[TallTed]

Perhaps consider not blurring "identity" and "identifier", so consider requestIdentifier which identifier might be dereferenceable in various ways (e.g., WebID, NetID, IdP-specific, RP-specific, etc.), and dereferencing each of which might retrieve a different set of attributes, and/or requestAttribute which might carry multiple arguments, e.g., requestAttribute ( height, weight, eye color, blood type, passport number....)?

[timcappalli]

2023-11-06 call:

• getIdentityAttributes
• getClaims
• getIdentityClaims
• getAttributes
• getClaims
• requestVerifiableClaim
• requestVerifiableAttributes

More preferred:

• requestClaims
• requestAttributes

Plan to close in two weeks.

[RByers]

Sounded like maybe requestClaims had the most support - let's go with that unless someone makes a stronger argument in the next two weeks?

[marcoscaceres]

I get the "claims" thing, but it smells bit a bit "lawyery" (no offense to any lawyers).

If successfully, responsibly deployed, the vast majority of uses of this API should return responses with particular properties or claims or proofs from a credential, but not what the developer might think of as the user's identity.

The properties are attached to "something" thought (i.e., identity documents). mDoc at least deals with "documents", and what you get back is a document representation, right? What do other standards give back.

How can we design an API that makes it clear that sites should ask for only what they need, and not over-ask?

The problem of over requesting is at the protocol layer, not at the request API. We can call it whatever, but the problem is that you can still do:

credintaisl.askVeryLittlePlease("{askForAllThings: true}"

So I just don't think we can restrict it anything at this level.

A more suitable mental model might be that, as developer, you are asking for basically a document template to be filled out - but hopefully with the understanding that there is not expectation that you will get back what you asked for.

So maybe, .requestIdentityProperties() or .requestIdentityAttributes()... hopefully making it more clear you (as a developer) are only going to get what you asked for (and that's a maybe, because they user may still choose not to share certain properties or attributes).

[npdoty]

Naming alone certainly won't protect against abusive overasking, but API design is something that is communicated to developers, and so it should be one place we communicate expectations.

Is the model that the developer gets back a document? Something like "age over 18" or "has a degree from an educational institution" aren't really document-like, but claim-like. While I understand "claims" to be the common term of art, I don't know what will actually be most comprehensible by developers that consume the API.

[hlozi]

"age over 18" or "has a degree from an educational institution" are documents when they are issued by an issuing authority attesting it. They are maybe claims when they are self asserted and that is not what we are covering with this API. What this API returns is not a claim it is more the document proving the claim.

[npdoty]

I own some document-like objects that show my birth date and that I have a PhD in information science from UC Berkeley. I haven't yet come across a document that says "this person is over 18" or a document that says "this person has an academic degree from an American college".

[marcoscaceres]

mDoc's mDL data literally has age_over_NN identifiers:

These identifiers are formatted as "age_over_NN," where "NN" is a number between 00 and 99, representing the specified age. The value of these identifiers can either be TRUE, indicating the holder is as old or older than the specified age, or FALSE, indicating they are younger.

[marcoscaceres]

As a non-mDoc/real-life example, please see also: https://www.vic.gov.au/proof-of-age-card

"The Victorian Proof of Age card can be used to show proof of age for people over 18 years. This card is recognised throughout Australia."

It can be used by people who don't have a driver's license to prove they are over 18 (e.g., to buy booze, enter night clubs, etc).

[npdoty]

That Australian Proof of Age card example includes a sample card ... that shows the holder's date of birth, full name and street address.

I just meant that we aren't accustomed to documents that only show assertions of particular claims, we are accustomed to documents that present a broad selection of identifying details about a person, from which one can draw claims, like a proof of their age. But I believe the goal for this work should be to emphasize the communication of claims, not of full identity documents.

[samuelgoto]

What this API returns is not a claim it is more the document proving the claim.

A credential?

[RByers]

The problem of over requesting is at the protocol layer, not at the request API. We can call it whatever, but the problem is that you can still do:
credintaisl.askVeryLittlePlease("{askForAllThings: true}"
So I just don't think we can restrict it anything at this level.

FWIW I absolutely think we can restrict this and just refuse to honor any request that refuses to list the properties it wants (or otherwise treat it as risky, as we may treat a custom-scheme invocation).

[timcappalli]

Notes from 2023-11-15 calls: https://github.com/WICG/identity-credential/wiki/2023-11-15-Meeting-Notes#api-design-should-emphasize-that-sites-should-request-minimal-properties-not-full-identity-documents

Highlighting an something from the discussion: support for selective disclosure could be mandated to be included in the registry for "protocol".

[timcappalli]

From 2024-07-29 call, comment added to #58. Closing issue.