fix spec links, add proper code example blocks, improve writting

Signed-off-by: pstlouis <[email protected]>

index.html

@@ -464,6 +464,7 @@ <h3>Storage Services</h3>
             (Verifier) &bull; Storage Service (Holder)
           </strong>
         </p>
+      </section>
       <section>
         <h3>Workflow Service</h3>
         <p>
@@ -1176,48 +1177,40 @@ <h4>Exchange Examples</h4>
     <section>
       <h3>Error Handling</h3>
       <p>
-        Error handling and messaging in the VC-API follows [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457.html). 
-        Implementers SHOULD include a [status](https://www.rfc-editor.org/rfc/rfc9457.html#name-status) 
-        and a [title](https://www.rfc-editor.org/rfc/rfc9457.html#name-title) 
-        in the error response body relating to the specifics of the endpoint on which the error occurs. 
+        Error handling and messaging in the VC-API aligns with Problem Details for HTTP APIs [[RFC9457]]. 
+        Implementers SHOULD include a status and a title in the error response body 
+        relating to the specifics of the endpoint on which the error occurs. 
       <p>
       <p>
         Aligning on error handling and messaging will greatly improve test-suites accuracy 
         when identifying technical friction impacting interoperability.
       </p>
       </p>
-        Leveraging other fields such as [detail](https://www.rfc-editor.org/rfc/rfc9457.html#name-detail), 
-        [instance](https://www.rfc-editor.org/rfc/rfc9457.html#name-instance),
-        and [type](https://www.rfc-editor.org/rfc/rfc9457.html#name-type) 
-        is encouraged, to provide more contextual feedback about the error, 
-        while being conscious of security concerns and hence not disclosing
-        sensitive information.
+        Leveraging other fields such as detail, instance and type is encouraged, 
+        to provide more contextual feedback about the error, 
+        while being conscious of security concerns and hence not disclosing sensitive information.
       </p>
       <p>
         Implementers should handle all server errors to the best of their capabilities. 
         Endpoints should avoid returning improperly handled 500 errors in production 
-        environments, as these may lead to [information disclosure](https://owasp.org/www-community/Improper_Error_Handling).
+        environments, as these may lead to information disclosure.
       </p>
-      <h4>Relationship between verification and error handling</h4>
+      <h4>Relationship between verification, validation and error handling</h4>
       <p>
-        An implementer should avoid raising errors while performing
-        [verification](https://w3c.github.io/vc-data-model/#verification), 
-        and instead should gather 
-        [ProblemDetails](https://w3c.github.io/vc-data-model/#problem-details) 
-        objects to include in the verification results.
+        It is recommended to avoid raising errors while performing verification, 
+        and instead gather ProblemDetails objects to include in the verification results.
       </p>
       <h4>Types of ProblemDetails</h4>
-        At the time of writting, ProblemDetails types refer to the [vc data model specification](https://w3c.github.io/vc-data-model/#problem-details)
-        It would be good to include additional types as time goes on.
-        <h5>Example ProblemDetails</h4>
-          <code>
+        An implementer can refer to the [[VC-DATA-MODEL-2.0]] and the [[VC-BITSTRING-STATUS-LIST]] for currently defined ProblemDetails types.
+        <pre class="example"
+          title="ProblemDetails">
           {
             "type": "https://www.w3.org/TR/vc-data-model#CRYPTOGRAPHIC_SECURITY_ERROR",
             "status": 400,
             "title": "CRYPTOGRAPHIC_SECURITY_ERROR",
             "detail": "The cryptographic security mechanism couldn't be verified. This is likely due to a malformed proof or an invalid verificationMethod."
           }
-          </code>
+        </pre>
       <h4>Verification Response</h4>
         <h5>Errors and Warnings</h5>
         Errors are ProblemDetails relating to cryptography, data model and malformed context.
@@ -1226,8 +1219,8 @@ <h5>Errors and Warnings</h5>
         The VerificationResponse object MUST have the verified value set to false if an error is included.
         The VerificationResponse object MUST have the verified value set to true if no errors are included.
 
-        <h5>Verification Response Example</h5>
-        <code>
+        <pre class="example"
+          title="Verification Response">
           {
             "verified": false,
             "document": verifiableCredential,
@@ -1237,7 +1230,7 @@ <h5>Verification Response Example</h5>
             "warnings": [ProblemDetails],
             "errors": [ProblemDetails]
           }
-        </code>
+        </pre>
     </section>
 
   </section>