414 problem details response

components/ProblemDetails.yml

@@ -0,0 +1,31 @@
+openapi: 3.0.0
+info:
+  version: "0.0.3-unstable"
+  title: VC API
+  description: This is an Experimental Open API Specification for the [VC Data Model](https://www.w3.org/TR/vc-data-model/).
+  license:
+    name: W3C Software and Document License
+    url: http://www.w3.org/Consortium/Legal/copyright-software.
+  contact:
+    name: GitHub Source Code
+    url: https://github.com/w3c-ccg/vc-api
+paths:
+components:
+  schemas:
+    ProblemDetails:
+      type: object
+      properties:
+        type:
+          type: string
+          description: URL identifying the type of problem.
+        title:
+          type: string
+          description: Short but specific human-readable string for the problem.
+        detail:
+          type: string
+          description: Longer human-readable string for the problem.
+      example: { 
+        "type": "https://www.w3.org/TR/vc-data-model#PARSING_ERROR", 
+        "title": "PARSING_ERROR", 
+        "detail": "There was an error while parsing input.", 
+      }

components/VerifyCredentialOptions.yml

@@ -17,10 +17,18 @@ components:
       additionalProperties: false
       description: Options for specifying how a credential is verified
       properties:
+        returnResults:
+          type: boolean
+          description: Include results for each verification steps taken in the response, such as verifying individual proofs, statuses and schemas.
+        returnProblemDetails:
+          type: boolean
+          description: Include ProblemDetails errors and warnings in the response.
         returnCredential:
           type: boolean
           description: Should the verified credential be returned in the response? If true, then the verified credential should be returned in the form in which it was verified. If false or not provided, then the verified credential should not be returned.
       example:
         {
-          "returnCredential": true
+          "returnProblemDetails": true,
+          "returnCredential": true,
+          "returnResults": true
         }

components/VerifyCredentialResult.yml

@@ -15,24 +15,100 @@ components:
     VerificationResult:
       type: object
       additionalProperties: false
-      description: Object summarizing a verification
+      description: Object to report the result of a verification process on a VerifiableCredential.
       properties:
-        checks:
-          type: array
-          description: The checks performed
-          items:
-            type: string
-        warnings:
-          type: array
-          description: Warnings
-          items:
-            type: string
-        errors:
-          type: array
-          description: Errors
-          items:
-            type: string
+        verified:
+          type: boolean
+          description: Overall verification assertion of the VerifiableCredential. This is set to `True` if no errors were detected during the verification process; otherwise, `False`. See error handling section for more guidance around errors, warnings, and validation and verification steps.
         credential:
           type: object
-          description: The verified credential
-      example: { "checks": ["proof"], "warnings": [], "errors": [] }
+          description: The VerifiableCredential used as the verification input.
+        problemDetails:
+          type: array
+          description: Array consisting of ProblemDetails objects.
+          items: 
+            $ref: "./ProblemDetails.yml#/components/schemas/ProblemDetails"
+        results:
+          type: object
+          additionalProperties: false
+          description: Verification results to be included as a more verbose output. Keys are mapped to properties from the Verifiable Credential Data Model which are subject to validations.
+          properties:
+            validFrom:
+              type: object
+              description: Results of validating the validFrom property, if present in the VerifiableCredential.
+              properties:
+                valid:
+                  type: boolean
+                  description: Validation result.
+                input:
+                  type: string
+                  description: The validFrom value.
+            validUntil:
+              type: object
+              description: Results of validating the validUntil property, if present in the VerifiableCredential.
+              properties:
+                valid:
+                  type: boolean
+                  description: Validation result.
+                input:
+                  type: string
+                  description: The validUntil value.
+            credentialSchema:
+              type: array
+              description: Results from validating the credentialSchema objects if any.
+              items:
+                type: object
+                description: Results from validating a credentialSchema object.
+                properties:
+                  valid:
+                    type: boolean
+                    description: Results of validating the credentialSchema object.
+                  input:
+                    type: object
+                    description: The credentialSchema object.
+            credentialStatus:
+              type: array
+              description: Results from validating the credentialStatus objects if any.
+              items:
+                type: object
+                description: Results of validating a credentialStatus object.
+                properties:
+                  value:
+                    type: integer
+                    description: Value of the statusEntry Bit.
+                  valid:
+                    type: boolean
+                    description: Results of validating the credentialStatus object.
+                  input:
+                    type: object
+                    description: The credentialStatus object.
+            proof:
+              type: array
+              description: Results from validating the proof objects if any.
+              items:
+                type: object
+                description: Results from validating a proof object.
+                properties:
+                  valid:
+                    type: boolean
+                    description: Results of validating the proof object.
+                  input:
+                    type: object
+                    description: The proof object.
+      example: { 
+        "verified": false, 
+        "credential": {},
+        "problemDetails": [
+          {
+            "title": "PARSING_ERROR",
+            "type": "https://www.w3.org/TR/vc-data-model#PARSING_ERROR "
+          }
+        ], 
+        "results": {
+          "validFrom": [], 
+          "validUntil": [], 
+          "credentialSchema": [], 
+          "credentialStatus": [], 
+          "proof": []
+        }
+      }

index.html

@@ -1071,6 +1071,11 @@ <h4>Relationship between verification, validation and error handling</h4>
       </p>
       <h4>Types of ProblemDetails</h4>
         An implementer can refer to the [[VC-DATA-MODEL-2.0]] and the [[VC-BITSTRING-STATUS-LIST]] for currently defined ProblemDetails types.
+        <p class="issue">
+          The example `type` URLs will work in the future after VCDM v2.0 becomes a global standard. 
+          To ensure the error links to the appropriate location, you can replace the base URL of 
+          `https://www.w3.org/TR/vc-data-model` with `www.w3.org/TR/vc-data-model-2.0` for the time being.
+        </p>
         <pre class="example"
           title="ProblemDetails">
           {