Skip to content

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.

Proposal Commentcontent typeapplication/jsontype [0]b679ded3-0e7c-41ba-89f8-da62a17898eatype [1]7808d2ba-d511-40af-84e8-c0d1625fdfdcidUUIDv7verUUIDv7refProposaltemplateProposal Comment TemplatereplyProposal Comment (Optional)sectionSection ReferencerevocationsVersion Revocationsbrand_idBrand Parameters (Optional)campaign_idCampaign Parameters (Optional)category_idCategory Parameters (Optional)ProposalProposal Comment TemplateBrand ParametersCampaign ParametersCategory Parameters <reply> OptionalOptionalOptionalOptional

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

Metadata

type

Parameter Value
Required yes
Format Document Type
Type b679ded3-0e7c-41ba-89f8-da62a17898ea,
7808d2ba-d511-40af-84e8-c0d1625fdfdc

The document TYPE.

Validation

MUST be a known document type.

id

Parameter Value
Required yes
Format UUIDv7

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.

Validation

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

ver

Parameter Value
Required yes
Format UUIDv7

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

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.

This is an Array of the format:

[ 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 ID of the Document being referenced.
  • document_ver is the UUIDv7 Version of the Document being referenced.

  • document_locator is a content unique locator for the document. This 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.

  • 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:

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

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 Template

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

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.

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.

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.

Validation

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

brand_id

Parameter Value
Required optional
Format Document Reference
Valid References Brand Parameters
Linked Reference Metadata ref
template
Exclusive campaign_id
category_id

A reference to the Brand Parameters Document this document lies under.

Validation

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

  • Any linked referenced document that includes a brand_id must match the brand_id of the referencing document.
  • MUST NOT be present in any document that contains campaign_id and category_id metadata.
  • The Document referenced by ref
  • MUST contain brand_id metadata; AND
  • MUST match the referencing documents brand_id value.
  • The Document referenced by template
  • MUST contain brand_id metadata; AND
  • MUST match the referencing documents brand_id value.

campaign_id

Parameter Value
Required optional
Format Document Reference
Valid References Campaign Parameters
Linked Reference Metadata ref
template
Exclusive brand_id
category_id

A reference to the Campaign Parameters Document this document lies under.

Validation

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

category_id

Parameter Value
Required optional
Format Document Reference
Valid References Category Parameters
Linked Reference Metadata ref
template
Exclusive brand_id
campaign_id

A reference to the Category Parameters Document this document lies under.

Validation

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

Payload

JSON Document which must validate against the referenced template.

Signers

The following user roles may sign documents of this type:

  • Registered

New versions of this document may be published by:

  • author
Copyright © 2024-2025 IOG Singapore, All Rights Reserved
License This document is licensed under CC-BY-4.0
Created 2024-12-27
Modified 2025-04-09
Authors Alex Pozhylenkov alex.pozhylenkov@iohk.io
Steven Johnson steven.johnson@iohk.io

Changelog

0.01 (2025-04-04)

  • First Published Version