Revisit presentation preview

features/0037-present-proof/README.md

@@ -35,11 +35,11 @@ Diagrams in this protocol were made in draw.io. To make changes:
 - export the picture and HTML to your local copy of this repo, and
 - submit a pull request.
 
-#### Choreography Diagram:
+### Choreography Diagram:
 
 ![present proof](credential-presentation.png)
 
-#### Propose Presentation
+### Propose Presentation
 
 An optional message sent by the Prover to the verifier to initiate a proof presentation process, or in response to a `request-presentation` message when the Prover wants to propose using a different presentation format. Schema:
 
@@ -57,7 +57,7 @@ Description of attributes:
 * `comment` -- a field that provides some human readable information about the proposed presentation.
 * `presentation_proposal` -- a JSON-LD object that represents the presentation example that Prover wants to provide. It should follow the schema of [Presentation Preview](#presentation-preview);
 
-#### Request Presentation
+### Request Presentation
 
 Request presentation is a message from a verifier to a prover that describes values that need to be revealed and predicates that need to be fulfilled. Schema:
 
@@ -84,7 +84,7 @@ Description of fields:
 * `request_presentations~attach` -- an array of attachments defining the acceptable formats for the presentation.
   * For Indy, the attachment contains data from libindy about the presentation request, base64 encoded, as returned from `libindy`. For more information see the [Libindy API](https://github.com/hyperledger/indy-sdk/blob/57dcdae74164d1c7aa06f2cccecaae121cefac25/libindy/src/api/anoncreds.rs#L1214).
 
-#### Presentation
+### Presentation
 
 This message is a response to a Presentation Request message and contains signed presentations. Schema:
 
@@ -111,66 +111,88 @@ Description of fields:
 * `presentations~attach` -- an array of attachments containing the presentation in the requested format(s).
   * For Indy, the attachment contains data from libindy that is the presentation, base64 encoded, as returned from `libindy`. For more information see the [Libindy API](https://github.com/hyperledger/indy-sdk/blob/57dcdae74164d1c7aa06f2cccecaae121cefac25/libindy/src/api/anoncreds.rs#L1404).
 
-#### Presentation Preview
+### Presentation Preview
 
 This is not a message but an inner object for other messages in this protocol. It is used to construct a preview of the data for the presentation. Its schema follows:
 
 ```json
 {
     "@type": "did:sov:BzCbsNYhMrjHiqZDTUASHg;spec/present-proof/1.0/presentation-preview",
-    "attributes": {
-        "<cred_def_id>": {
-            "<attribute>": {
-                "mime-type": "<type>",
-                "encoding": "<encoding>",
-                "value": "<value>"
-            }
-        },
-        ...
-    },
-    "predicates": {
-        "<cred_def_id>": {
-            "<predicate>": {
-                "<attribute>": "<threshold>",
-                ...
-            },
-            ...
-        },
-        ...
-    },
-    "non_revocation_times": {
-        "<cred_def_id>": "<iso_8601_datetime>",
-        ...
-    }
+    "attributes": [
+        {
+            "name": "<attribute_name>",
+            "cred_def_id": "<cred_def_id>",
+            "mime-type": "<type>",
+            "encoding": "<encoding>",
+            "value": "<value>"
+        }
+    ],
+    "predicates": [
+        {
+            "name": "<attribute_name>",
+            "cred_def_id": "<cred_def_id>",
+            "predicate": "<predicate>",
+            "threshold": <threshold>
+        }
+    ]
 }
 ```
 
-The preview identifies attributes, predicates, and non-revocation timestamps by credential definition identifier. Note that this composition assumes that any presentation can include information from at most one credential per credential definition; such an approach mitigates corroboration risk.
+The preview identifies attributes and predicates to present.
+
+#### Attributes
+
+The mandatory `"attributes"` key maps to a list (possibly empty to propose a presentation with no attributes) of specifications, one per attribute. Each such specification proposes its attribute's characteristics for creation within a presentation.
+
+##### Attribute Name
+
+The mandatory `"name"` key maps to the name of the attribute.
+
+##### Credential Definition Identifier
+
+The optional `"cred_def_id"` key maps to the credential definition identifier of the credential with the current attribute. If the key is absent, the preview specifies attribute's posture in the presentation as a self-attested attribute.
+
+##### Attribute Metadata (MIME Type and Encoding)
+
+The optional `"mime-type"` and `"encoding"` keys specify any MIME type and encoding metadata pertaining to the attribute. Their values default to `"text/plain"` and `null` respectively.
+
+##### Value
+
+The `"value"` key maps to the proposed value of the attribute to reveal within the presentation. An attribute specification must specify a `"value"`, a `"cred_def_id"`, or both: 
+
+* if the `"value"` key is present and the `"cred_def_id"` key is absent, the preview proposes a self-attested attribute;
+* if the `"value"` key and the `"cred_def_id"` are both present, the preview proposes verifiable claim to reveal in the presentation;
+* if the `"value"` key is absent and the `"cred_def_id"` key is present, the preview proposes verifiable claim not to reveal in the presentation.
+
+#### Predicates
+
+The mandatory `"predicates"` key maps to a list (possibly empty to propose a presentation with no predicates) of predicate specifications, one per predicate. Each such specification proposes its predicate's characteristics for creation within a presentation.
 
-##### Attributes
+##### Attribute Name
 
-The `"attributes"` key maps zero or more credential definition identifiers to one or more inner objects; each such inner object maps an attribute name to its respective MIME types, encodings, and values (all optional) for the presentation:
+The mandatory `"name"` key maps to the name of the attribute germane to the predicate.
 
-* the prover may include a MIME type and/or encoding per attribute in the preview for verifier information on how to interpret its value
-* the value itself may be absent at this stage; its omission in the preview indicates its ultimate inclusion in the presentation itself.
+##### Credential Definition Identifier
 
-Any attribute specified per credential definition identifier must belong to its corresponding credential definition. In this way the structure excludes a bait-and-switch where the prover has credentials on multiple credential definitions with common attribute names (e.g., `name`, `score`).
+The mandatory `"cred_def_id"` key maps to the credential definition identifier of the credential with the current attribute.
 
-For consistency and completeness, an empty production `"{}"` as the value for the `"attributes"` key denotes that the preview specifies zero attributes.
+##### Predicate
 
-##### Predicates
+The mandatory `"predicate"` key maps to the predicate operator: `"<"`, `"<="`, `">="`, `">"`. 
 
-The `"predicates"` key maps zero or more credential definition identifiers to one or more inner objects; each such inner object maps predicate names to their respective attributes and thresholds for the presentation. Each predicate name identifies its comparison operator: `"<"`, `"<="`, `">"`, `">="`. Each attribute so specified per credential definition identifier must belong to its corresponding credential definition.
+##### Threshold Value
 
-For consistency and completeness, an empty production `"{}"` as the value for the `"predicates"` key denotes that the preview specifies zero predicates.
+The mandatory `"threshold"` key maps to the threshold value for the predicate.
 
-##### Non-Revocation Timestamps
+##### Filter
 
-The `"non_revocation_times"` key maps zero or more credential definition identifiers to ISO 8601 datetimes, each of which offers an instant where the prover or verifier proposes inclusion of proof of the non-revocation of its corresponding credential in the presentation.
+The mandatory `"filter"` key maps to an object with one or more criteria disjunctively (via "or") applicable to the attribute as a claim.
 
-Non-revocation timestamps apply only to credentials on credential definitions that support revocation.
+Filter keys include:
 
-For consistency and completeness, an empty production `"{}"` as the value for the `"non_revocation_times"` key denotes that the preview specifies zero non-revocation timestamps.
+* `"cred_def_id"` to specify a credential definition identifier
+* `"schema_id"` to specify a schema identifier
+* any other criteria that both the holder and verifier understand in the context of presentation creation.
 
 ## Negotiation and Preview
 
@@ -187,7 +209,7 @@ The presentation preview as proposed above does not allow nesting of predicate l
 
 The presentation preview may be indy-centric, as it assumes the inclusion of at most one credential per credential definition. In addition, it prescribes exactly four predicates and assumes mutual understanding of their semantics (e.g., could `">="` imply a lexicographic order for non-integer values, and if so, where to specify character collation algorithm?).
 
-Finally, the inclusion of a non-revocation timestamp may be premature at the preview stage.
+Finally, the inclusion of non-revocation timestamps may become desirable at the preview stage; the standard as proposed does not accommodate such.
 
 ## Rationale and alternatives