Metadata Fields

Metadata Types

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

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

; document_ref


; Reference to another Signed Document
document_ref = [ 1* [
  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 Validation

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

ref

Parameter	Value
Required	optional
Format	Document Reference
Valid References	Proposal Meta Template
	Proposal Template
	Proposal
	Proposal Comment Meta Template
	Proposal Comment Template
	Proposal Comment
	Proposal Submission Action
	Proposal Moderation Action
	Comment Moderation Action
	Brand Parameters
	Campaign Parameters
	Category Parameters
	Decision Parameters

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:

• 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 Meta Template
	Proposal Template
	Proposal Comment Meta Template
	Proposal Comment 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
	Decision 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.

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