Skip to content

Proposal

Description

A Proposal is a document which describes a proposed solution or project to address the criteria of a category within a campaign.

The proposal itself is a draft document, it is not submitted for consideration unless a Proposal Submission Action is submitted which references it.

Proposals 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 is controlled by its template.

ProposalProposal Document    Relationshipscluster_system_parametersSystem ParametersProposal Template                         Proposal Template                    Proposal                         Proposal                    content typeapplication/jsontype7808d2ba-d511-40af-84e8-c0d1625fdfdcidDocument IdverDocument VertemplateProposal TemplatecollaboratorsCollaborators Reference ListrevocationsVersion RevocationsparametersBrand ParametersCampaign ParametersCategory ParametersProposal:e->Proposal Template:w1*Brand Parameters                             Brand Parameters                        Proposal:e->Brand Parameters1*Proposal Comment                         Proposal Comment                    Proposal Comment:e->Proposal:w1*Proposal Moderation Action                         Proposal Moderation Action                    Proposal Moderation Action:e->Proposal:w1*Proposal Submission Action                         Proposal Submission Action                    Proposal Submission Action:e->Proposal:w1*Campaign Parameters                             Campaign Parameters                        Category Parameters                             Category Parameters                        

Validation

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

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

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 are registered as proposers.
  • That the document has been signed validly according to the validation rules.

COSE Header Parameters

Metadata

type

Parameter Value
Required yes
Format Document Type
Type 7808d2ba-d511-40af-84e8-c0d1625fdfdc

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 Validation

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

template

Parameter Value
Required yes
Format Document Reference
Valid References Proposal 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.

collaborators

Parameter Value
Required optional
Format Collaborators Reference List

A list of collaborators who may also publish updates to versions of this document. This should include all parties who have not signed this document directly.

Every subsequent version can amend the collaborators list. However, the initial Author can never be removed from being able to publish a new version of the document.

collaborators Validation

This list does not imply these collaborators have consented to collaborate, only that the author/s are permitting these potential collaborators to participate in the drafting and submission process. However, any document submission referencing a proposal MUST be signed by all collaborators in addition to the author.

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 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.
  • The Document referenced by template
  • MUST contain parameters metadata; AND
  • MUST match the referencing documents parameters value.

Payload

Proposal Document drafted for submission to a category of a campaign.

Must be valid according to the schema contained within the Document Reference from the template metadata.

Signers

The following user roles may sign documents of this type:

  • Proposer

New versions of this document may be published by:

  • author
  • collaborators
Copyright © 2024-2025 IOG Singapore, All Rights Reserved
License This document is licensed under CC-BY-4.0
Created 2024-12-27
Modified 2025-05-05
Authors Alex Pozhylenkov alex.pozhylenkov@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.