Confusing terminology

[rohan-wire]

Hi,

Disclosure is used at least two ways in the document.

• to refer to the array containing the salt, (maybe name), and value.
• to refer to the base64url encoded string

It's easy to understand how this could have happened, as both contain logically the same information. I propose explicitly calling these:

• disclosure array, and
• disclosure presentation

I also propose calling the hash/digest of the disclosure the disclosure digest in full in every use. The only time we would use "disclosure" without one of these modifiers is talking about the process of disclosing in general.

As for the plaintext of the claims that can be disclosed, I propose blinded claim.

So the first paragraph of Section 4.1 would read:

An SD-JWT consists of:

• a signed JSON document,
• a list of disclosure presentations (each of which reveals a blinded claim), and
• optionally an issuer key binding (discussed in Section 4.3).

The signed JSON document (the JWT body) contains plaintext claims; and disclosure digests, each of which either refers to a specific blinded claim or is a decoy. The holder can include zero or more disclosure presentations without breaking the signature of the JWT body. The contents of the blinded claims cannot be modified, because the corresponding digest would no longer match any digest in the JWT body. Blinded claims can be individual object properties (key-value pairs) or array elements.

[danielfett]

This is appreciated! I agree that we should be more consistent with our terms. I'm not sure about "disclosure presentation" as "presentation" suggests a specific meaning. Maybe just "disclosure" and "disclosure contents" is fine.

[bc-pi]

The current document attempts to mostly use "Disclosure" to mean the base64url encoded string. I think that works okay. Places where it's referring to the decoded JSON array should be fixed to be more clear. So I think I agree that "disclosure" and where needed "disclosure contents" would be good.

[bc-pi]

PR #410 has editorial updates for more consistent treatment of a Disclosure vs the contents of a Disclosure