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.

Proposalcontent typeapplication/jsontype [0]7808d2ba-d511-40af-84e8-c0d1625fdfdcidUUIDv7verUUIDv7templateProposal TemplatecollaboratorsCollaborators Reference ListrevocationsVersion Revocationsbrand_idBrand Parameters (Optional)campaign_idCampaign Parameters (Optional)category_idCategory Parameters (Optional)Proposal TemplateBrand ParametersCampaign ParametersCategory Parameters OptionalOptionalOptional

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.

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.

template

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

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.

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.

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

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-04-09
Authors Alex Pozhylenkov alex.pozhylenkov@iohk.io
Steven Johnson steven.johnson@iohk.io

Changelog

0.01 (2025-04-04)

  • First Published Version