From 45d9c5bc9d0932e65723de7ab39befc1aab98e0e Mon Sep 17 00:00:00 2001
From: Markus Sabadello <markus@danubetech.com>
Date: Fri, 29 Mar 2024 11:10:36 +0100
Subject: [PATCH] Various additional information about states.

---
 index.html   | 33 +++++++++++++++++++++++----------
 spec/spec.md | 33 +++++++++++++++++++++++----------
 2 files changed, 46 insertions(+), 20 deletions(-)

diff --git a/index.html b/index.html
index 01b767b..8020c85 100644
--- a/index.html
+++ b/index.html
@@ -450,6 +450,19 @@ <h3 id="jobid"><a class="toc-anchor" href="#jobid" >§</a> <code>jobId</code></h
 <span class="token punctuation">}</span>
 </code></pre>
 <h3 id="didstate"><a class="toc-anchor" href="#didstate" >§</a> <code>didState</code></h3>
+<p>This output field contains an object with the following fields:</p>
+<ul>
+<li><a href="#didstatestate" ><code>didState.state</code></a>: The current state of DID operations.</li>
+<li><a href="#didstatedid" ><code>didState.did</code></a>: The DID at the end of the DID operation.</li>
+<li><a href="#didstatesecret" ><code>didState.secret</code></a>: An object with DID controller keys and other secrets.</li>
+<li><a href="#didstatediddocument" ><code>didState.didDocument</code></a>: The DID document after the DID operation has been successfully executed.</li>
+</ul>
+<p>In <a href="#client-managed-secret-mode" >Client-managed Secret Mode</a>, this output field MAY contain one or more of the following:</p>
+<ul>
+<li>A <code>verificationMethodTemplate</code> property with a JSON array containing one or more <a href="#verification-method-template" >Verification Method Template</a> objects.</li>
+<li>A <code>signingRequest</code> property with a <a href="#signing-request-set" >Signing Request Set</a>.</li>
+<li>A <code>decryptionRequest</code> property with a <a href="#decryption-request-set" >Decryption Request Set</a>.</li>
+</ul>
 <h4 id="didstatestate"><a class="toc-anchor" href="#didstatestate" >§</a> <code>didState.state</code></h4>
 <p>This output field contains the current state of the DID operations. It is used to indicate if a DID operation
 is finished, failed, or if a longer-running “job” has been created that requires additional steps.</p>
@@ -773,11 +786,11 @@ <h3 id="didstatestatewait"><a class="toc-anchor" href="#didstatestatewait" >§</
 <h2 id="data-structures"><a class="toc-anchor" href="#data-structures" >§</a> Data Structures</h2>
 <p>This specification defines a number of data structures that appear in the <a href="#input-fields" >input fields</a> and <a href="#output-fields" >output fields</a>.</p>
 <h3 id="verification-method-public-data"><a class="toc-anchor" href="#verification-method-public-data" >§</a> Verification Method Public Data</h3>
-<p>This data structure is used when public data about a verification method is exchanged between the client and the DID Registrar, as follows:</p>
+<p>This data structure is used as follows, when public data about a verification method is exchanged between the client and the DID Registrar:</p>
 <ul>
-<li>In <a href="#client-managed-secret-mode" >Client-managed Secret Mode</a> inside the <a href="#secret" ><code>secret</code> input field</a>,
+<li>In <a href="#client-managed-secret-mode" >Client-managed Secret Mode</a> as a <code>verificationMethod</code> field inside the <a href="#secret" ><code>secret</code> input field</a>,
 when the client invokes the DID Registrar again after it received a <a href="#didstateactiongetverificationmethod" ><code>didState.action=&quot;getVerificationMethod&quot;</code> output field</a>.</li>
-<li>In <a href="#client-managed-secret-mode" >Client-managed Secret Mode</a> inside the <a href="#didstatesecret" ><code>didState.secret</code> output field</a>,
+<li>In <a href="#client-managed-secret-mode" >Client-managed Secret Mode</a> as a <code>verificationMethod</code> field inside the <a href="#didstatesecret" ><code>didState.secret</code> output field</a>,
 when the DID Registrar responds to a client request.</li>
 </ul>
 <p>A <strong>Verification Method Public Data</strong> structure is a JSON object based on the verification method
@@ -817,11 +830,11 @@ <h3 id="verification-method-public-data"><a class="toc-anchor" href="#verificati
 <span class="token punctuation">}</span>
 </code></pre>
 <h3 id="verification-method-private-data"><a class="toc-anchor" href="#verification-method-private-data" >§</a> Verification Method Private Data</h3>
-<p>This data structure is used when private data about a verification method is exchanged between the client and the DID Registrar, as follows:</p>
+<p>This data structure is used as follows, when private data about a verification method is exchanged between the client and the DID Registrar:</p>
 <ul>
-<li>In <a href="#internal-secret-mode" >Internal Secret Mode</a> inside the <a href="#secret" ><code>secret</code> input field</a>,
+<li>In <a href="#internal-secret-mode" >Internal Secret Mode</a> as a <code>verificationMethod</code> field inside the <a href="#secret" ><code>secret</code> input field</a>,
 when the client invokes the DID Registrar again after it received a <a href="#didstateactiongetverificationmethod" ><code>didState.action=&quot;getVerificationMethod&quot;</code> output field</a>.</li>
-<li>In <a href="#internal-secret-mode" >Internal Secret Mode</a> inside the <a href="#didstatesecret" ><code>didState.secret</code> output field</a>,
+<li>In <a href="#internal-secret-mode" >Internal Secret Mode</a> as a <code>verificationMethod</code> field inside the <a href="#didstatesecret" ><code>didState.secret</code> output field</a>,
 when the DID Registrar responds to a client request.</li>
 </ul>
 <p>A <strong>Verification Method Private Data</strong> structure is a JSON object based on the <a href="#verification-method-public-data" >Verification Method Public Data</a>
@@ -857,7 +870,7 @@ <h3 id="verification-method-private-data"><a class="toc-anchor" href="#verificat
 <h3 id="verification-method-template"><a class="toc-anchor" href="#verification-method-template" >§</a> Verification Method Template</h3>
 <p>This data structure is used as follows:</p>
 <ul>
-<li>In <a href="#client-managed-secret-mode" >Client-managed Secret Mode</a> inside the <a href="#didstatestate" ><code>didState.state</code> output field</a>,
+<li>In <a href="#client-managed-secret-mode" >Client-managed Secret Mode</a> as <code>verificationMethodTemplate</code> field inside the <a href="#didstate" ><code>didState</code> output field</a>,
 when the DID Registrar responds to a client request with a <a href="#didstateactiongetverificationmethod" ><code>didState.action=&quot;getVerificationMethod&quot;</code> output field</a>.</li>
 </ul>
 <p>A <strong>Verification Method Template</strong> structure is a JSON object based on the verification method
@@ -892,7 +905,7 @@ <h3 id="verification-method-template"><a class="toc-anchor" href="#verification-
 <h3 id="signing-request-set"><a class="toc-anchor" href="#signing-request-set" >§</a> Signing Request Set</h3>
 <p>This data structure is used as follows:</p>
 <ul>
-<li>In <a href="#client-managed-secret-mode" >Client-managed Secret Mode</a> as a <code>signingRequest</code> field inside the <a href="#didstatestate" ><code>didState.state</code> output field</a>,
+<li>In <a href="#client-managed-secret-mode" >Client-managed Secret Mode</a> as a <code>signingRequest</code> field inside the <a href="#didstate" ><code>didState</code> output field</a>,
 when the DID Registrar responds to a client request with a <a href="#didstateactionsignpayload" ><code>didState.action=&quot;signPayload&quot;</code> output field</a>.</li>
 </ul>
 <p>A <strong>Signing Request Set</strong> structure is a JSON object. Each property name in that JSON object is called a <em>signing request ID</em>, and
@@ -959,7 +972,7 @@ <h3 id="signing-response-set"><a class="toc-anchor" href="#signing-response-set"
 <h3 id="decryption-request-set"><a class="toc-anchor" href="#decryption-request-set" >§</a> Decryption Request Set</h3>
 <p>This data structure is used as follows:</p>
 <ul>
-<li>In <a href="#client-managed-secret-mode" >Client-managed Secret Mode</a> inside the <a href="#didstatestate" ><code>didState.state</code> output field</a>,
+<li>In <a href="#client-managed-secret-mode" >Client-managed Secret Mode</a> as a <code>decryptionRequest</code> field inside the <a href="#didstate" ><code>didState</code> output field</a>,
 when the DID Registrar responds to a client request with a <a href="#didstateactiondecryptpayload" ><code>didState.action=&quot;decryptPayload&quot;</code> output field</a>.</li>
 </ul>
 <p>A <strong>Decryption Request Set</strong> structure is a JSON object. Each property name in that JSON object is called a <em>decryption request ID</em>, and
@@ -989,7 +1002,7 @@ <h3 id="decryption-request-set"><a class="toc-anchor" href="#decryption-request-
 <h3 id="decryption-response-set"><a class="toc-anchor" href="#decryption-response-set" >§</a> Decryption Response Set</h3>
 <p>This data structure is used as follows:</p>
 <ul>
-<li>In <a href="#client-managed-secret-mode" >Client-managed Secret Mode</a> inside the <a href="#secret" ><code>secret</code> input field</a>,
+<li>In <a href="#client-managed-secret-mode" >Client-managed Secret Mode</a> as a <code>decryptionResponse</code> field inside the <a href="#secret" ><code>secret</code> input field</a>,
 when the client invokes the DID Registrar again after it received a <a href="#didstateactiondecryptpayload" ><code>didState.action=&quot;decryptPayload&quot;</code> output field</a>.</li>
 </ul>
 <p>A <strong>Decryption Response Set</strong> structure is a JSON object. Each property name MUST match a <em>decryption request ID</em> which was previously received by the
diff --git a/spec/spec.md b/spec/spec.md
index f049bc5..a291615 100644
--- a/spec/spec.md
+++ b/spec/spec.md
@@ -482,6 +482,19 @@ Example:
 
 ### `didState`
 
+This output field contains an object with the following fields:
+
+* [`didState.state`](#didstatestate): The current state of DID operations.
+* [`didState.did`](#didstatedid): The DID at the end of the DID operation.
+* [`didState.secret`](#didstatesecret): An object with DID controller keys and other secrets.
+* [`didState.didDocument`](#didstatediddocument): The DID document after the DID operation has been successfully executed.
+
+In [Client-managed Secret Mode](#client-managed-secret-mode), this output field MAY contain one or more of the following:
+
+* A `verificationMethodTemplate` property with a JSON array containing one or more [Verification Method Template](#verification-method-template) objects.
+* A `signingRequest` property with a [Signing Request Set](#signing-request-set).
+* A `decryptionRequest` property with a [Decryption Request Set](#decryption-request-set).
+
 #### `didState.state`
 
 This output field contains the current state of the DID operations. It is used to indicate if a DID operation
@@ -901,11 +914,11 @@ This specification defines a number of data structures that appear in the [input
 
 ### Verification Method Public Data
 
-This data structure is used when public data about a verification method is exchanged between the client and the DID Registrar, as follows:
+This data structure is used as follows, when public data about a verification method is exchanged between the client and the DID Registrar:
 
-- In [Client-managed Secret Mode](#client-managed-secret-mode) inside the [`secret` input field](#secret),
+- In [Client-managed Secret Mode](#client-managed-secret-mode) as a `verificationMethod` field inside the [`secret` input field](#secret),
   when the client invokes the DID Registrar again after it received a [`didState.action="getVerificationMethod"` output field](#didstateactiongetverificationmethod).
-- In [Client-managed Secret Mode](#client-managed-secret-mode) inside the [`didState.secret` output field](#didstatesecret),
+- In [Client-managed Secret Mode](#client-managed-secret-mode) as a `verificationMethod` field inside the [`didState.secret` output field](#didstatesecret),
   when the DID Registrar responds to a client request.
 
 A **Verification Method Public Data** structure is a JSON object based on the verification method
@@ -949,11 +962,11 @@ Example:
 
 ### Verification Method Private Data
 
-This data structure is used when private data about a verification method is exchanged between the client and the DID Registrar, as follows:
+This data structure is used as follows, when private data about a verification method is exchanged between the client and the DID Registrar:
 
-- In [Internal Secret Mode](#internal-secret-mode) inside the [`secret` input field](#secret),
+- In [Internal Secret Mode](#internal-secret-mode) as a `verificationMethod` field inside the [`secret` input field](#secret),
   when the client invokes the DID Registrar again after it received a [`didState.action="getVerificationMethod"` output field](#didstateactiongetverificationmethod).
-- In [Internal Secret Mode](#internal-secret-mode) inside the [`didState.secret` output field](#didstatesecret),
+- In [Internal Secret Mode](#internal-secret-mode) as a `verificationMethod` field inside the [`didState.secret` output field](#didstatesecret),
   when the DID Registrar responds to a client request.
 
 A **Verification Method Private Data** structure is a JSON object based on the [Verification Method Public Data](#verification-method-public-data)
@@ -996,7 +1009,7 @@ Example:
 
 This data structure is used as follows:
 
-- In [Client-managed Secret Mode](#client-managed-secret-mode) inside the [`didState.state` output field](#didstatestate),
+- In [Client-managed Secret Mode](#client-managed-secret-mode) as `verificationMethodTemplate` field inside the [`didState` output field](#didstate),
   when the DID Registrar responds to a client request with a [`didState.action="getVerificationMethod"` output field](#didstateactiongetverificationmethod).
 
 A **Verification Method Template** structure is a JSON object based on the verification method
@@ -1035,7 +1048,7 @@ Example **Verification Method Template** containing properties `purpose` and `ty
 
 This data structure is used as follows:
 
-- In [Client-managed Secret Mode](#client-managed-secret-mode) as a `signingRequest` field inside the [`didState.state` output field](#didstatestate),
+- In [Client-managed Secret Mode](#client-managed-secret-mode) as a `signingRequest` field inside the [`didState` output field](#didstate),
   when the DID Registrar responds to a client request with a [`didState.action="signPayload"` output field](#didstateactionsignpayload).
 
 A **Signing Request Set** structure is a JSON object. Each property name in that JSON object is called a _signing request ID_, and
@@ -1112,7 +1125,7 @@ Example **Signing Response Set** containing two **Signing Responses**:
 
 This data structure is used as follows:
 
-- In [Client-managed Secret Mode](#client-managed-secret-mode) inside the [`didState.state` output field](#didstatestate),
+- In [Client-managed Secret Mode](#client-managed-secret-mode) as a `decryptionRequest` field inside the [`didState` output field](#didstate),
   when the DID Registrar responds to a client request with a [`didState.action="decryptPayload"` output field](#didstateactiondecryptpayload).
 
 A **Decryption Request Set** structure is a JSON object. Each property name in that JSON object is called a _decryption request ID_, and
@@ -1147,7 +1160,7 @@ Example **Decryption Request Set** containing two **Decryption Requests** with I
 
 This data structure is used as follows:
 
-- In [Client-managed Secret Mode](#client-managed-secret-mode) inside the [`secret` input field](#secret), 
+- In [Client-managed Secret Mode](#client-managed-secret-mode) as a `decryptionResponse` field inside the [`secret` input field](#secret), 
   when the client invokes the DID Registrar again after it received a [`didState.action="decryptPayload"` output field](#didstateactiondecryptpayload).
 
 A **Decryption Response Set** structure is a JSON object. Each property name MUST match a _decryption request ID_ which was previously received by the