Skip to content

Rep Nomination

Description

A Representative Nomination Document is created to opt in as a Representative Voter for a specific Contest on a Brand/Campaign or Category.

This Document is a kind of Profile that is primarily used to help justify the Representatives Nomination to prospective delegators.

The user must have registered as a Representative. The presence of this document signifies the user's intent to participate in that contest as a Representative.

The document's structure is defined by the associated Rep Nomination Form Template. This allows an Admin to specify contest-specific requirements.

The Representative can retract their nomination by using the revoke metadata to revoke this Nomination document.

It is an extension of all other profiles attached to the same Catalyst ID.

Profiles themselves are intentionally general, however they may be linked to a Brand/Campaign/Category via the template used by the profile.

The payload of a profile is controlled by its template.

Rep NominationRep Nomination Document    RelationshipsRep Profile                         Rep Profile                    Rep Nomination Form Template                         Rep Nomination Form Template                    Contest Parameters                         Contest Parameters                    Rep Nomination                         Rep Nomination                    content typeapplication/jsontypebf9abd97-5d1f-4429-8e80-740fea371a9c94579df1-a6dc-433b-a8e8-910c5dc2f0e3idDocument IdverDocument VerrefRep ProfiletemplateRep Nomination Form TemplaterevocationsVersion RevocationsparametersContest ParametersRep Nomination:e->Rep Profile:w1*Rep Nomination:e->Rep Nomination Form Template:w1*Rep Nomination:e->Contest Parameters:w1*Contest Delegation                         Contest Delegation                    Contest Delegation:e->Rep Nomination:w1*

Validation

  • The signer MUST be a registered 'Representative'.
  • The 'ref' metadata field MUST point to a valid 'Representative Profile' document.
  • The 'parameters' metadata field MUST point to a valid 'Contest Parameters' document.
  • The 'template' metadata field MUST point to a valid 'Representative Nomination Form Template' document.
  • The payload MUST be valid against the JSON schema defined in the referenced template.
  • Other rules may apply as defined by the Contest or other parameters which can control who may validly nominate as a representative in a Contest.

No Nomination is valid unless the latest Contest Delegation of the Delegate refers to their own Nomination. This requires that Nominating is a two step process:

  1. Post the Nomination Document.
  2. Post a Contest Delegation delegating to the new Nomination Document.

Updating the Nomination Document will invalidate all Nominations to the Representative.

This is because Delegation points to a SPECIFIC Nomination, and it MUST be the latest for the Representative on the Contest. As the Nomination contains information that the User relies on when choosing to delegate, changing that information could have a real and detrimental result in the Delegation choice. Therefore, for a Delegation to be valid, it MUST point to the latest Nomination for a Representative.

Business Logic

Front End

  • Allows a Representative to create or update their profile for a category.
  • The Representative sets their status to 'active' to be discoverable for delegation.
  • The Representative revokes the Nomination to signal they are no longer participating in the category.
  • Nominations are not valid if the latest Delegation by the Representative does NOT reference their latest Nomination.

Back End

  • The backend MUST verify the signer is a 'Representative' and that all referenced documents exist.
  • The system will only consider Representatives as having valid Nominations if:
  • Their latest Nomination in a Contest is not Revoked.
  • Their latest Delegation in a Contest references their latest Nomination.

COSE Header Parameters

Metadata

type

Parameter Value
Required yes
Format Document Type
Type bf9abd97-5d1f-4429-8e80-740fea371a9c,
94579df1-a6dc-433b-a8e8-910c5dc2f0e3

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

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:

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

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

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

Payload

The Representative's profile data for a specific contest. Its structure is defined by the referenced template document.

In the case of Revoking a nomination the payload is nil.

Signers

The following User roles may sign documents of this type:

  • Representative

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-06-19
Authors Alex Pozhylenkov alex.pozhylenkov@iohk.io
Neil McAuliffe neil.mcauliffe@iohk.io
Steven Johnson steven.johnson@iohk.io

Changelog

0.01 (2025-06-19)

  • First Published Version