feat(docs): Add more doc definitions/specifications (#285)

* fix(docs): Updated TODO place holder text with context

* fix(docs): Render docs with better placeholder

* docs(docs): Add more detail to proposal document specification

* docs(docs): Add details to the Proposal Comment document

* docs(docs): Add more proposal submission actions specifications

* docs(docs): random cleanups

* docs(docs): fix markdown lint issues

* docs(docs): Use a CID for the document hash

* docs(docs): Add document revocations to proposals and comments

* docs(docs): turn hash into a map for better future proofing

* docs(docs): Use defined cbor tag and binary format for IPLD Content Identifiers (CID)

* docs(docs): Removed obsolete cddl definition

---------

Co-authored-by: neil-iohk <[email protected]>

Author: stevenj

docs/src/architecture/08_concepts/signed_doc/doc_relationships.d2

@@ -100,6 +100,7 @@ copyright: |~md
   "ver": UUIDv7
   "template": Proposal Template
   "collaborators": Collaborators Reference List
+  "revocations": Version Revocations
   "brand_id": Brand Parameters (Optional)
   "campaign_id": Campaign Parameters (Optional)
   "category_id": Category Parameters (Optional)
@@ -123,6 +124,7 @@ copyright: |~md
   "template": Proposal Comment Template
   "reply": Proposal Comment (Optional)
   "section": Section Reference
+  "revocations": Version Revocations
   "brand_id": Brand Parameters (Optional)
   "campaign_id": Campaign Parameters (Optional)
   "category_id": Category Parameters (Optional)

docs/src/architecture/08_concepts/signed_doc/doc_relationships.svg

@@ -106,18 +106,40 @@ Reference to a Linked Document or Documents.
 This is the primary hierarchical reference to a related document.
 
 This is an Array of the format:
-    `[[DocumentID, DocumentVer, DocumentHash],...]`
 
-* `DocumentID` is the [UUIDv7][RFC9562-V7] ID of the Document being referenced.
-* `DocumentVer` is the [UUIDv7][RFC9562-V7] Version of the Document being referenced.
-* `DocumentHash` is the Blake2b-256 Hash of the entire document being referenced, not just its payload.
-  It ensures that the intended referenced document is the one used, and there has been no substitution.
-  Prevents substitutions where a new document with the same Document ID and Ver might be published over an existing one.
+```cddl
+[ 1* [ document_id, document_ver, document_locator ] ]
+```
+
+If a reference is defined as required, there must be at least 1 reference specified.
+Some documents allow multiple references, and they are documented as required.
+
+* `document_id` is the [UUIDv7][RFC9562-V7] ID of the Document being referenced.
+* `document_ver` is the [UUIDv7][RFC9562-V7] Version of the Document being referenced.
+* `document_locator` is a content unique locator for the document.
+  This serves two purposes.
+
+  1. It ensures that the document referenced by an ID/Version is not substituted.
+     In other words, that the document intended to be referenced, is actually referenced.
+  2. Allow the document to be unambiguously located in decentralized storage systems.
+
+  There can be any number of Document Locations in any reference.
+  The currently defined locations are:
+
+  * `cid` : A [CBOR Encoded IPLD Content Identifier][CBOR-TAG-42] ( AKA an [IPFS CID][IPFS-CID] ).
+  * Others may be added when further storage mechanisms are defined.
+
+  The value set here does not guarantee that the document is actually stored.
+  It only defines that if it were stored, this is the identifier that
+  that is required to retrieve it.
 
 #### Validation
 
-Every Reference Document **MUST** Exist, and **MUST** be a valid reference to the document.
-The calculated Hash of the Referenced Document **MUST** match the Hash in the reference.
+The following must be true for a valid reference:
+
+* The Referenced Document **MUST** Exist
+* Every value in the `document_locator` must consistently reference the exact same document.
+* The `document_id` and `document_ver` **MUST** match the values in the referenced document.
 
 ## Payload
 
@@ -149,6 +171,8 @@ New versions of this document may be published by:
 
 * First Published Version
 
+[CBOR-TAG-42]: https://github.com/ipld/cid-cbor/
 [RFC9052-HeaderParameters]: https://www.rfc-editor.org/rfc/rfc8152#section-3.1
 [CC-BY-4.0]: https://creativecommons.org/licenses/by/4.0/legalcode
+[IPFS-CID]: https://docs.ipfs.tech/concepts/content-addressing/#what-is-a-cid
 [RFC9562-V7]: https://www.rfc-editor.org/rfc/rfc9562.html#name-uuid-version-7

docs/src/architecture/08_concepts/signed_doc/docs/comment_moderation_action.md

@@ -22,6 +22,7 @@ The payload of a proposal is controlled by its template.
   "ver": UUIDv7
   "template": Proposal Template
   "collaborators": Collaborators Reference List
+  "revocations": Version Revocations
   "brand_id": Brand Parameters (Optional)
   "campaign_id": Campaign Parameters (Optional)
   "category_id": Category Parameters (Optional)
@@ -36,26 +37,40 @@ The payload of a proposal is controlled by its template.
 
 ### Validation
 
-This specification outlines the required definitions for the current features.
-The document will be incrementally improved in future iterations as more functionality
-and features are added.
-This section will be included and updated in future iterations.
+The first version of a Proposal *MUST* be signed by the original author.
+It may optionally be co-signed by any of the listed [`collaborators`](../metadata.md#collaborators).
+It may not be signed by anyone else.
+
+Subsequent Versions can be signed/co-signed by either the Original Author of the first version,
+OR any of the listed [`collaborators`](../metadata.md#collaborators) in the immediately previous version.
+This allows any collaborator to update the next version of a document, provided they are still a collaborator.
+It is valid for a proposal to be signed by a collaborator
+who is no longer listed as in the [`collaborators`](../metadata.md#collaborators)
+of the document they are signing, provided they are listed as a collaborator in the immediately previous document version.
+This allows for a collaborator to make an update to the document which removes themselves
+from the [`collaborators`](../metadata.md#collaborators) list.
+
+All versions of the document *MUST* list the author as the original author.
+The Author can not be changed by any document revision.
 
 ### Business Logic
 
 #### Front End
 
-This specification outlines the required definitions for the current features.
-The document will be incrementally improved in future iterations as more functionality
-and features are added.
-This section will be included and updated in future iterations.
+As validity of the documents is currently enforced by the backend,
+the front end does not need to validate the document has been signed
+correctly.
+It may do so, but it is not required.
 
 #### Back End
 
-This specification outlines the required definitions for the current features.
-The document will be incrementally improved in future iterations as more functionality
-and features are added.
-This section will be included and updated in future iterations.
+Before accepting a new proposal to be published, the backend will ensure:
+
+* The document has been signed by a valid author or collaborator.
+* That the signer of the document was a registered proposer
+* That the document was signed with their proposers key
+* That all listed [`collaborators`](../metadata.md#collaborators) are registered as proposers.
+* That the document has been signed validly according to the [validation](#validation) rules.
 
 ## [COSE Header Parameters][RFC9052-HeaderParameters]
 
@@ -144,6 +159,33 @@ are permitting these potential collaborators to participate in the drafting and
 However, any document submission referencing a proposal MUST be signed by all collaborators in
 addition to the author.
 
+### [`revocations`](../metadata.md#revocations)
+<!-- markdownlint-disable MD033 -->
+| Parameter | Value |
+| --- | --- |
+| Required | optional |
+| Format | [Version Revocations](../metadata.md#version-revocations) |
+<!-- markdownlint-enable MD033 -->
+A document may include a list of any prior versions which are considered to be revoked.
+Only the revocation list in the latest version of the document applies.
+Revoked documents are flagged as no longer valid, and should not be displayed.
+As a special case, if the revocations are set to `true` then all versions of the document
+are revoked, including the latest document.
+
+In this case, when the latest document is revoked, the payload may be empty.
+Any older document that has [`revocations`](../metadata.md#revocations) set to `true` is always to be filtered
+and its payload is to be assumed to be invalid.
+
+This allows for an entire document and any/all published versions to be revoked.
+A new version of the document that is published after this, may reinstate prior
+document versions, by not listing them as revoked.
+However, any document where revocations was set `true` can never be reinstated.
+
+#### Validation
+
+If the field is `true` the payload may be absent or invalid.
+Such documents may never be submitted.
+
 ### [`brand_id`](../metadata.md#brand_id)
 <!-- markdownlint-disable MD033 -->
 | Parameter | Value |

docs/src/architecture/08_concepts/signed_doc/docs/proposal.md

@@ -2,8 +2,6 @@
 
 ## Description
 
-## Proposal Comment Document
-
 A Proposal Comment is a document which comments on a referenced Proposal document.
 
 Proposal Comments themselves are intentionally general, however they may be
@@ -23,6 +21,7 @@ The payload of a proposal comment is controlled by its template.
   "template": Proposal Comment Template
   "reply": Proposal Comment (Optional)
   "section": Section Reference
+  "revocations": Version Revocations
   "brand_id": Brand Parameters (Optional)
   "campaign_id": Campaign Parameters (Optional)
   "category_id": Category Parameters (Optional)
@@ -39,26 +38,28 @@ The payload of a proposal comment is controlled by its template.
 
 ### Validation
 
-This specification outlines the required definitions for the current features.
-The document will be incrementally improved in future iterations as more functionality
-and features are added.
-This section will be included and updated in future iterations.
+A comment which is a reply *MUST* reference the same document.
+It may reference a different version of the document.
 
 ### Business Logic
 
 #### Front End
 
-This specification outlines the required definitions for the current features.
-The document will be incrementally improved in future iterations as more functionality
-and features are added.
-This section will be included and updated in future iterations.
+Comments are valid for any version of the document, however
+as comments refer to a specific version of a document, they may
+lose context when displayed against the latest version of a document.
+In these cases, the front end should clearly show that a comment was on
+a different version of the document.
+
+If the front end posts a reply to another comment:
+
+* it should reference the comment being replied to in the [`reply`](../metadata.md#reply) field.
+* The [`ref`](../metadata.md#ref) field must refer to the same document, but can be a different version.
 
 #### Back End
 
-This specification outlines the required definitions for the current features.
-The document will be incrementally improved in future iterations as more functionality
-and features are added.
-This section will be included and updated in future iterations.
+The backend will only validate the document being referenced exists,
+and the integrity of the [`ref`](../metadata.md#ref) and [`reply`](../metadata.md#reply) metadata fields is correct.
 
 ## [COSE Header Parameters][RFC9052-HeaderParameters]
 
@@ -123,18 +124,40 @@ Reference to a Linked Document or Documents.
 This is the primary hierarchical reference to a related document.
 
 This is an Array of the format:
-  `[[DocumentID, DocumentVer, DocumentHash],...]`
 
-* `DocumentID` is the [UUIDv7][RFC9562-V7] ID of the Document being referenced.
-* `DocumentVer` is the [UUIDv7][RFC9562-V7] Version of the Document being referenced.
-* `DocumentHash` is the Blake2b-256 Hash of the entire document being referenced, not just its payload.
-  It ensures that the intended referenced document is the one used, and there has been no substitution.
-  Prevents substitutions where a new document with the same Document ID and Ver might be published over an existing one.
+```cddl
+[ 1* [ document_id, document_ver, document_locator ] ]
+```
+
+If a reference is defined as required, there must be at least 1 reference specified.
+Some documents allow multiple references, and they are documented as required.
+
+* `document_id` is the [UUIDv7][RFC9562-V7] ID of the Document being referenced.
+* `document_ver` is the [UUIDv7][RFC9562-V7] Version of the Document being referenced.
+* `document_locator` is a content unique locator for the document.
+  This serves two purposes.
+
+  1. It ensures that the document referenced by an ID/Version is not substituted.
+     In other words, that the document intended to be referenced, is actually referenced.
+  2. Allow the document to be unambiguously located in decentralized storage systems.
+
+  There can be any number of Document Locations in any reference.
+  The currently defined locations are:
+
+  * `cid` : A [CBOR Encoded IPLD Content Identifier][CBOR-TAG-42] ( AKA an [IPFS CID][IPFS-CID] ).
+  * Others may be added when further storage mechanisms are defined.
+
+  The value set here does not guarantee that the document is actually stored.
+  It only defines that if it were stored, this is the identifier that
+  that is required to retrieve it.
 
 #### Validation
 
-Every Reference Document **MUST** Exist, and **MUST** be a valid reference to the document.
-The calculated Hash of the Referenced Document **MUST** match the Hash in the reference.
+The following must be true for a valid reference:
+
+* The Referenced Document **MUST** Exist
+* Every value in the `document_locator` must consistently reference the exact same document.
+* The `document_id` and `document_ver` **MUST** match the values in the referenced document.
 
 ### [`template`](../metadata.md#template)
 <!-- markdownlint-disable MD033 -->
@@ -181,6 +204,33 @@ A Reference to the original document, or the comment being replied to.
 For a non-reply this must be a valid section reference into the referenced document.
 For a reply, this must be a valid section reference into the comment being replied to.
 
+### [`revocations`](../metadata.md#revocations)
+<!-- markdownlint-disable MD033 -->
+| Parameter | Value |
+| --- | --- |
+| Required | optional |
+| Format | [Version Revocations](../metadata.md#version-revocations) |
+<!-- markdownlint-enable MD033 -->
+A document may include a list of any prior versions which are considered to be revoked.
+Only the revocation list in the latest version of the document applies.
+Revoked documents are flagged as no longer valid, and should not be displayed.
+As a special case, if the revocations are set to `true` then all versions of the document
+are revoked, including the latest document.
+
+In this case, when the latest document is revoked, the payload may be empty.
+Any older document that has [`revocations`](../metadata.md#revocations) set to `true` is always to be filtered
+and its payload is to be assumed to be invalid.
+
+This allows for an entire document and any/all published versions to be revoked.
+A new version of the document that is published after this, may reinstate prior
+document versions, by not listing them as revoked.
+However, any document where revocations was set `true` can never be reinstated.
+
+#### Validation
+
+If the field is `true` the payload may be absent or invalid.
+Such documents may never be submitted.
+
 ### [`brand_id`](../metadata.md#brand_id)
 <!-- markdownlint-disable MD033 -->
 | Parameter | Value |
@@ -301,7 +351,9 @@ New versions of this document may be published by:
 
 * First Published Version
 
+[CBOR-TAG-42]: https://github.com/ipld/cid-cbor/
 [RFC9052-HeaderParameters]: https://www.rfc-editor.org/rfc/rfc8152#section-3.1
 [CC-BY-4.0]: https://creativecommons.org/licenses/by/4.0/legalcode
+[IPFS-CID]: https://docs.ipfs.tech/concepts/content-addressing/#what-is-a-cid
 [RFC9562-V7]: https://www.rfc-editor.org/rfc/rfc9562.html#name-uuid-version-7
 [RFC8259]: https://www.rfc-editor.org/rfc/rfc8259.html

docs/src/architecture/08_concepts/signed_doc/docs/proposal_comment.md

@@ -106,18 +106,40 @@ Reference to a Linked Document or Documents.
 This is the primary hierarchical reference to a related document.
 
 This is an Array of the format:
-  `[[DocumentID, DocumentVer, DocumentHash],...]`
 
-* `DocumentID` is the [UUIDv7][RFC9562-V7] ID of the Document being referenced.
-* `DocumentVer` is the [UUIDv7][RFC9562-V7] Version of the Document being referenced.
-* `DocumentHash` is the Blake2b-256 Hash of the entire document being referenced, not just its payload.
-  It ensures that the intended referenced document is the one used, and there has been no substitution.
-  Prevents substitutions where a new document with the same Document ID and Ver might be published over an existing one.
+```cddl
+[ 1* [ document_id, document_ver, document_locator ] ]
+```
+
+If a reference is defined as required, there must be at least 1 reference specified.
+Some documents allow multiple references, and they are documented as required.
+
+* `document_id` is the [UUIDv7][RFC9562-V7] ID of the Document being referenced.
+* `document_ver` is the [UUIDv7][RFC9562-V7] Version of the Document being referenced.
+* `document_locator` is a content unique locator for the document.
+  This serves two purposes.
+
+  1. It ensures that the document referenced by an ID/Version is not substituted.
+     In other words, that the document intended to be referenced, is actually referenced.
+  2. Allow the document to be unambiguously located in decentralized storage systems.
+
+  There can be any number of Document Locations in any reference.
+  The currently defined locations are:
+
+  * `cid` : A [CBOR Encoded IPLD Content Identifier][CBOR-TAG-42] ( AKA an [IPFS CID][IPFS-CID] ).
+  * Others may be added when further storage mechanisms are defined.
+
+  The value set here does not guarantee that the document is actually stored.
+  It only defines that if it were stored, this is the identifier that
+  that is required to retrieve it.
 
 #### Validation
 
-Every Reference Document **MUST** Exist, and **MUST** be a valid reference to the document.
-The calculated Hash of the Referenced Document **MUST** match the Hash in the reference.
+The following must be true for a valid reference:
+
+* The Referenced Document **MUST** Exist
+* Every value in the `document_locator` must consistently reference the exact same document.
+* The `document_id` and `document_ver` **MUST** match the values in the referenced document.
 
 ## Payload
 
@@ -149,6 +171,8 @@ New versions of this document may be published by:
 
 * First Published Version
 
+[CBOR-TAG-42]: https://github.com/ipld/cid-cbor/
 [RFC9052-HeaderParameters]: https://www.rfc-editor.org/rfc/rfc8152#section-3.1
 [CC-BY-4.0]: https://creativecommons.org/licenses/by/4.0/legalcode
+[IPFS-CID]: https://docs.ipfs.tech/concepts/content-addressing/#what-is-a-cid
 [RFC9562-V7]: https://www.rfc-editor.org/rfc/rfc9562.html#name-uuid-version-7