Metadata Fields¶

Metadata Types¶

The following types of metadata have been defined. All Metadata fields use one of these types.

Chain Link¶

A link to a previous document in a chained sequence.

CDDL Specification

cddl/chain.cddl

; chain


; Reference to the previous Signed Document in a sequence.
; * `height` is of the CURRENT block.
; * `document_ref` is *ONLY* omitted in the very first document in a sequence.
chain = [height, ? document_ref]

; The consecutive sequence number of the current document
; in the chain.
; The very first document in a sequence is numbered `0` and it
; *MUST ONLY* increment by one for each successive document in
; the sequence.
;
; The FINAL sequence number is encoded with the current height
; sequence value, negated.
;
; For example the following values for height define a chain
; that has 5 documents in the sequence 0-4, the final height
; is negated to indicate the end of the chain:
; `0, 1, 2, 3, -4`
;
; No subsequent document can be chained to a sequence that has
; a final chain height.
height = int

; Reference to a single Signed Document
document_ref = [
  document_id,
  document_ver,
  document_locator
]

; Document ID
document_id = uuid_v7

; UUIDv7
uuid_v7 = #6.37(bytes .size 16)

; Document Version
document_ver = uuid_v7

; Where a document can be located, must be a unique identifier.
document_locator = {
  "cid" => cid
}

; IPLD content identifier
; TODO: add size limits if possible
cid = #6.42(bytes)

Collaborators Reference List¶

A list of collaborators who can participate in drafting and submitting a document

CDDL Specification

cddl/collaborators.cddl

; collaborators


; Allowed Collaborators on the next subsequent version of a document.
collaborators = [ * catalyst_id_kid ]

; UTF8 Catalyst ID URI encoded as a bytes string.
catalyst_id_kid = bytes

Document Id¶

A unique document identifier

CDDL Specification

cddl/document_id.cddl

; Unique Document Identifier


; Document ID
document_id = uuid_v7

; UUIDv7
uuid_v7 = #6.37(bytes .size 16)

Document Reference¶

A document reference identifier

CDDL Specification

cddl/document_refs.cddl

; document_refs


; Reference to one or more Signed Documents
document_refs = [ 1* document_ref ]

; Reference to a single Signed Document
document_ref = [
  document_id,
  document_ver,
  document_locator
]

; Document ID
document_id = uuid_v7

; UUIDv7
uuid_v7 = #6.37(bytes .size 16)

; Document Version
document_ver = uuid_v7

; Where a document can be located, must be a unique identifier.
document_locator = {
  "cid" => cid
}

; IPLD content identifier
; TODO: add size limits if possible
cid = #6.42(bytes)

Document Type¶

A document type identifier

CDDL Specification

cddl/document_type.cddl

; Unique Document Type Identifier


; Document Type
document_type = [ 1* uuid_v4 ]

; UUIDv4
uuid_v4 = #6.37(bytes .size 16)

Document Ver¶

A unique chronological document version

CDDL Specification

cddl/document_ver.cddl

; Unique Chronological Document Version Identifier


; Document Version
document_ver = uuid_v7

; UUIDv7
uuid_v7 = #6.37(bytes .size 16)

Section Reference¶

A document section reference identifier

CDDL Specification

cddl/section_ref.cddl

; section_ref


; Reference to a section in a referenced document.
section_ref = json_pointer

; RFC6901 Standard JSON Pointer
json_pointer = text

UUIDv4 ¶

Version 4 formatted UUID

CDDL Specification

cddl/uuid_v4.cddl

; Version 4 UUID
; See: https://www.rfc-editor.org/rfc/rfc9562.html#name-uuid-version-4
;      https://github.com/lucas-clemente/cbor-specs/blob/master/uuid.md


; UUIDv4
uuid_v4 = #6.37(bytes .size 16)

UUIDv7 ¶

Version 7 formatted UUID

CDDL Specification

cddl/uuid_v7.cddl

; Version 7 UUID
; See: https://www.rfc-editor.org/rfc/rfc9562.html#name-uuid-version-7
;      https://github.com/lucas-clemente/cbor-specs/blob/master/uuid.md


; UUIDv7
uuid_v7 = #6.37(bytes .size 16)

Version Revocations¶

A list of all versions of this document which are 'revoked'.

CDDL Specification

cddl/revocations.cddl

; revocations


; List of revoked versions of this document.
revocations = [ * document_ver ] / true

; Document Version
document_ver = uuid_v7

; UUIDv7
uuid_v7 = #6.37(bytes .size 16)

Individual Metadata field definitions¶

`type`¶

Parameter	Value
Required	yes
Format	Document Type

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

when a document changes over time, such as with a new version of a particular document that supersedes an earlier one.
when a new document in a sequence of documents is produced.

Because the most common use ver is a new version of the same document this is to be assumed unless the document specifies its representing a sequence of documents.

`ver` Validation¶

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

`ref`¶

Parameter	Value
Required	optional
Format	Document Reference
Valid References	Proposal Form Template
	Proposal Presentation Template
	Proposal
	Proposal Comment Form Template
	Proposal Comment Presentation Template
	Proposal Comment
	Proposal Submission Action
	Proposal Moderation Action
	Comment Moderation Action
	Brand Parameters
	Brand Parameters Form Template
	Campaign Parameters
	Campaign Parameters Form Template
	Category Parameters
	Category Parameters Form Template
	Contest Parameters
	Contest Parameters Form Template
	Rep Profile
	Rep Profile Form Template
	Rep Nomination
	Rep Nomination Form Template
	Contest Delegation

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	optional
Format	Document Reference
Valid References	Proposal Form Template
	Proposal Comment Form Template
	Brand Parameters Form Template
	Campaign Parameters Form Template
	Category Parameters Form Template
	Contest Parameters Form Template
	Rep Profile Form Template
	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.

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

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

`parameters`¶

Parameter	Value
Required	optional
Format	Document Reference
Valid References	Brand Parameters
	Campaign Parameters
	Category Parameters
	Contest Parameters

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.

`chain`¶

Parameter	Value
Required	optional
Format	Chain Link

An immutable link to the previous document in a chained sequence of documents. Because ID/Ver only defines values for the current document, and is not intended by itself to prevent insertion of documents in a sequence, the chain metadata allows for the latest document to directly point to its previous iteration.

It also aids in discoverability, where the latest document may be pinned but prior documents can be discovered automatically by following the chain.

`chain` Validation¶

Chained Documents do not support collaborators. Any document which is attempted to be published in the sequence which is NOT published by the author of the first document in the sequence is fraudulent, and to be discarded.

In addition, the chained document MUST:

Not have collaborators;
Have the same id as the document being chained to;
Have a ver that is greater than the ver being chained to;
Have the same type as the chained document;
Have parameters match;
Have not be chaining to a document already chained to by another document;
Have its absolute height exactly one more than the height of the document being chained to.

IF any of these validations fail, then the entire sequence of documents is INVALID. Not just the current document.

Example of a Valid Chain¶

classDiagram
    direction LR
    class Last {
        type: "=Intermediate.Document Type"
        id: "=Intermediate.Document ID"
        ver: ">Intermediate.Document ID"
        parameters: "=Intermediate.Document Parameters"
        chain.height: -2
        chain.document_ref: "=Intermediate"

        author(Intermediate.Catalyst ID)
    }
    style Last stroke:#060,stroke-width:4px

    class Intermediate {
        type: "=First.Document Type"
        id: "=First.Document ID"
        ver: ">First.Document ID"
        parameters: "=First.Document Parameters"
        chain.height: 1
        chain.document_ref: "=First"

        author(First.Catalyst ID)
    }
    style Intermediate stroke:#060,stroke-width:4px

    class First {
        type: "Document Type"
        id: "Document ID"
        ver: "=Document ID"
        parameters: "Document Parameters"
        chain.height: 0
        chain.document_ref: None

        author(Catalyst ID)
    }
    style First stroke:#060,stroke-width:4px

    Last --|> Intermediate : chains to
    Intermediate --|> First : chains to

Example of an Invalid Chain¶

Either of the two documents being present invalidates the data in the entire chain, as they are signed by the author of the chain.

classDiagram
    direction LR

    class Last {
        type: "=Intermediate.Document Type"
        id: "=Intermediate.Document ID"
        ver: ">Intermediate.Document ID"
        parameters: "=Intermediate.Document Parameters"
        chain.height: -2
        chain.document_ref: "=Intermediate"

        author(Intermediate.Catalyst ID)
    }
    style Last stroke:#f60,stroke-width:4px

    class Intermediate {
        type: "=First.Document Type"
        id: "=First.Document ID"
        ver: ">First.Document ID"
        parameters: "=First.Document Parameters"
        chain.height: 1
        chain.document_ref: "=First"

        author(First.Catalyst ID)
    }
    style Intermediate stroke:#f60,stroke-width:4px

    class First {
        type: "Document Type"
        id: "Document ID"
        ver: "=Document ID"
        parameters: "Document Parameters"
        chain.height: 0
        chain.document_ref: None

        author(Catalyst ID)
    }
    style First stroke:#f60,stroke-width:4px

    Last --|> Intermediate : chains to
    Intermediate --|> First : chains to

    class Invalid_Chain {
        type: "=First.Document Type"
        id: "=First.Document ID"
        ver: ">Intermediate.Document ID"
        parameters: "=First.Document Parameters"
        chain.height: 1
        chain.document_ref: "=First"

        author(First.Catalyst ID)
    }

    Invalid_Chain --|> First : Invalidly chains to
    style Invalid_Chain fill:#100,stroke:#f00,stroke-width:4px


    class After_Final {
        type: "=Final.Document Type"
        id: "=Final.Document ID"
        ver: ">Final.Document ID"
        parameters: "=Final.Document Parameters"
        chain.height: 3
        chain.document_ref: "=Last"

        author(Last.Catalyst ID)
    }

    After_Final --|> Last : Invalidly chains to
    style After_Final fill:#100,stroke:#f00,stroke-width:4px

Example of a Fraudulent Chain Document¶

The invalid document does not invalidate the chain, as its not signed by the author of the chained documents.

classDiagram
    direction LR
    class Last {
        type: "=Intermediate.Document Type"
        id: "=Intermediate.Document ID"
        ver: ">Intermediate.Document ID"
        parameters: "=Intermediate.Document Parameters"
        chain.height: -2
        chain.document_ref: "=Intermediate"

        author(Intermediate.Catalyst ID)
    }
    style Last stroke:#060,stroke-width:4px

    class Intermediate {
        type: "=First.Document Type"
        id: "=First.Document ID"
        ver: ">First.Document ID"
        parameters: "=First.Document Parameters"
        chain.height: 1
        chain.document_ref: "=First"

        author(First.Catalyst ID)
    }
    style Intermediate stroke:#060,stroke-width:4px

    class First {
        type: "Document Type"
        id: "Document ID"
        ver: "=Document ID"
        parameters: "Document Parameters"
        chain.height: 0
        chain.document_ref: None

        author(Catalyst ID)
    }
    style First stroke:#060,stroke-width:4px

    Last --|> Intermediate : chains to
    Intermediate --|> First : chains to

    class Rejected {
        type: "=First.Document Type"
        id: "=First.Document ID"
        ver: ">Intermediate.Document ID"
        parameters: "=Intermediate.Document Parameters"
        chain.height: 1
        chain.document_ref: "=First"

        author(Other.Catalyst ID)
    }

    Rejected --|> Intermediate : Invalidly chains to
    style Rejected fill:#100,stroke:#f00,stroke-width:4px

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

Metadata Fields¶

Metadata Types¶

Chain Link¶

Collaborators Reference List¶

Document Id¶

Document Reference¶

Document Type¶

Document Ver¶

Section Reference¶

UUIDv4¶

UUIDv7¶

Version Revocations¶

Individual Metadata field definitions¶

type¶

type Validation¶

id¶

id Validation¶

ver¶

ver Validation¶

ref¶

ref Validation¶

template¶

template Validation¶

reply¶

reply Validation¶

section¶

section Validation¶

collaborators¶

collaborators Validation¶

revocations¶

parameters¶

parameters Validation¶

chain¶

chain Validation¶

Example of a Valid Chain¶

Example of an Invalid Chain¶

Example of a Fraudulent Chain Document¶

Copyright¶

UUIDv4 ¶

UUIDv7 ¶

`type`¶

`type` Validation¶

`id`¶

`id` Validation¶

`ver`¶

`ver` Validation¶

`ref`¶

`ref` Validation¶

`template`¶

`template` Validation¶

`reply`¶

`reply` Validation¶

`section`¶

`section` Validation¶

`collaborators`¶

`collaborators` Validation¶

`revocations`¶

`parameters`¶

`parameters` Validation¶

`chain`¶

`chain` Validation¶