Proposal Comment¶

Description¶

A Proposal Comment is a document which comments on a referenced Proposal document.

Proposal Comments themselves are intentionally general, however they may be linked to a brand/campaign or category via the template used by the proposal.

The payload of a proposal comment is controlled by its template.

Validation¶

A comment which is a reply MUST reference the same document. It may reference a different version of the document.

Business Logic¶

Front End¶

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 field.
The ref field must refer to the same document, but can be a different version.

Back End¶

The backend will only validate the document being referenced exists, and the integrity of the ref and reply metadata fields is correct.

COSE Header Parameters ¶

content type = application/json
content-encoding = [br]

Metadata¶

`type`¶

Parameter	Value
Required	yes
Format	Document Type
Type	b679ded3-0e7c-41ba-89f8-da62a17898ea

The document TYPE.

`type` Validation¶

MUST be a known document type.

`id`¶

Parameter	Value
Required	yes
Format	Document Id

Document ID, created the first time the document is created. This must be a properly created UUIDv7 which contains the timestamp of when the document was created.

`id` Validation¶

IF ver does not == id then a document with id and ver being equal MUST exist.

`ver`¶

Parameter	Value
Required	yes
Format	Document Ver

The unique version of the document. The first version of the document must set ver == id

ver represents new versions of the same document as it changes over time.

`ver` Validation¶

The document version must always be >= the document ID.

`ref`¶

Parameter	Value
Required	yes
Format	Document Reference
Valid References	Proposal

Reference to a Linked Document or Documents. This is the primary hierarchical reference to a related document.

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.

The document reference serves two purposes:

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.
It Allows 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 ( AKA an IPFS CID ).
Others may be added when further storage mechanisms are defined.

The document location does not guarantee that the document is actually stored. It only defines that if it were stored, this is the identifier that is required to retrieve it. Therefore it is required that Document References are unique and reproducible, given a documents contents.

`ref` Validation¶

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`¶

Parameter	Value
Required	yes
Format	Document Reference
Valid References	Proposal Comment Form Template

Reference to the template used to create and/or validate this document.

`template` Validation¶

In addition to the validation performed for Document Reference type fields, The document payload is not valid if it does not validate completely against the referenced template.

`reply`¶

Parameter	Value
Required	optional
Format	Document Reference
Valid References	Proposal Comment

Reference to a Comment document type being referred to.

`reply` Validation¶

In addition to the validation performed for Document Reference type fields, The ref of the reply document must be the same as the original comment document.

`section`¶

Parameter	Value
Required	optional
Format	Section Reference

A Reference to the original document, or the comment being replied to.

`section` Validation¶

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`¶

Parameter	Value
Required	optional
Format	Version Revocations

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 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.

`revocations` Validation¶

If the field is true the payload may be absent or invalid. Such documents may never be submitted.

`parameters`¶

Parameter	Value
Required	yes
Format	Document Reference
Valid References	Brand Parameters
	Campaign Parameters
	Category Parameters
Linked Reference Metadata	`ref`
	`template`

A reference to the Parameters Document this document lies under.

`parameters` Validation¶

In addition to the validation performed for Document Reference type fields:

Any linked referenced document that includes a parameters metadata must match the parameters of the referencing document, or a parent of those parameters.

For example, a linked reference to Contest Parameters is transitively a reference to the Parameters document it references, and each parameters document they reference until the Brand parameters document is reached.

The use case here is for Templates. The profile template, or proposal templates could be defined at any of these levels, and as long as they all refer to the same chain of parameters in the hierarchy they are all valid.

The Document referenced by ref
MUST contain parameters metadata; AND
MUST match the referencing documents parameters value.
The Document referenced by template
MUST contain parameters metadata; AND
MUST match the referencing documents parameters value.

Payload¶

JSON Document which must validate against the referenced template.

Signers¶

The following User roles may sign documents of this type:

Registered

Only the original author can update and sign a new version of documents.

Copyright¶

Copyright	2024-2025 IOG Singapore, All Rights Reserved
License	This document is licensed under CC-BY-4.0
Created	2024-12-27
Modified	2025-10-24
Authors	Alex Pozhylenkov alex.pozhylenkov@iohk.io
	Nathan Bogale nathan.bogale@iohk.io
	Neil McAuliffe neil.mcauliffe@iohk.io
	Steven Johnson steven.johnson@iohk.io

Changelog¶

0.01 (2025-04-04)¶

First Published Version

0.03 (2025-05-05)¶

Use generalized parameters.