Skip to content

Commit 3a98a31

Browse files
committed
fix(specs): Resolve collaborators field contradiction in Conditions documents
- Override collaborators description in Conditions to clarify they cannot update - Update Conditions document update rule documentation to state only author can update - Add drafts requirement: conditions must be included on every submission including drafts - Add collaborators exclusion: only document signer must accept conditions, not collaborators - Update JSON, CUE, and markdown documentation for consistency - Aligns with plan requirements for explicit acceptance, drafts, and individual signer responsibility
1 parent f8b68a3 commit 3a98a31

File tree

4 files changed

+42
-7
lines changed

4 files changed

+42
-7
lines changed

docs/src/architecture/08_concepts/signed_doc/docs/conditions.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -255,8 +255,8 @@ For example:
255255
* Contest-level conditions should be signed by Contest Admin or a parent-level
256256
admin
257257

258-
Updates are allowed by the original author and from the 'collaborators' metadata field
259-
of the previous submitted document's version.
258+
Updates are allowed only by the original author of the document.
259+
Collaborators listed in the `collaborators` metadata field do not have permission to update Conditions documents.
260260

261261
## JSON Specification Requirements
262262

@@ -337,7 +337,7 @@ Add a new entry to the `docs` section with the following structure:
337337
"user": []
338338
},
339339
"update": {
340-
"description": "Updates are allowed by the original author and from the 'collaborators' metadata field of the previous submitted document's version.",
340+
"description": "Only the original author can update and sign a new version of documents.",
341341
"type": "author"
342342
}
343343
},

docs/src/architecture/08_concepts/signed_doc/metadata.md

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -488,6 +488,18 @@ The validation process for user-submitted documents involves transitive collecti
488488
becomes required and must be present in the user document. **If the unified list is empty** (no conditions are
489489
required), the `conditions` field may be omitted.
490490

491+
**Drafts Requirement**: Conditions must be included on **every submission**, including draft versions of proposals
492+
or other documents. This ensures positive and current assent at every stage of document creation. Without this
493+
requirement, a user could accept terms for the first draft, change their mind, and then submit a subsequent draft
494+
without the terms, meaning their assent is no longer positively asserted. It also ensures that rules, such as those
495+
against objectionable material, apply to the document at every stage of its creation.
496+
497+
**Collaborators Exclusion**: The acceptance of terms is tied to the act of submission by an individual. The terms
498+
and conditions apply only to the individual who signs and submits the document. Collaborators listed on the
499+
document are **not required** to accept the conditions. This mirrors how contracts typically work, where each
500+
party must sign individually. Only the document author (signer) must include the `conditions` field to indicate
501+
their acceptance.
502+
491503
**Validation Rules:**
492504

493505
* The user document's `conditions` array must exactly match the union of all required conditions from the parameter hierarchy

specs/definitions/signed_docs/docs/conditions.cue

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -84,6 +84,29 @@ docs: #DocumentDefinitions & {
8484
type: signed_doc_types.allDocNames
8585
}
8686

87+
collaborators: {
88+
required: "optional"
89+
description: """
90+
A list of collaborators who may be associated with this document.
91+
92+
**Important**: For Conditions documents, only the original author can update
93+
and sign new versions. Collaborators listed here do not have permission to
94+
publish updates to this document. This field is optional and may be used for
95+
documentation or organizational purposes only.
96+
"""
97+
validation: """
98+
For Conditions documents, collaborators do not have update permissions.
99+
Only the original author can create new versions of Conditions documents.
100+
101+
In the event there are **MULTIPLE** `collaborators` listed, they **MUST** be
102+
sorted.
103+
104+
Sorting for each element of `collaborators` follows the same sort order as
105+
specified for Map Keys, as defined by CBOR Deterministic Encoding
106+
(4.3.2 Length-First Map Key Ordering).
107+
"""
108+
}
109+
87110
revocations: required: "optional"
88111
}
89112

specs/signed_doc.json

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1659,10 +1659,10 @@
16591659
"validation": "Chained Documents do not support collaborators.\nAny document which is attempted to be published in the sequence\nwhich is *NOT* published by the author of the first document in the\nsequence is fraudulent, and to be discarded.\n\nIn addition, the chained document *MUST*:\n\n* Not have `collaborators`;\n* Have the same `id` as the document being chained to;\n* Have a `ver` that is greater than the `ver` being chained to;\n* Have the same `type` as the chained document;\n* Have `parameters` match;\n* Have not be chaining to a document already chained to by another document;\n* Have its absolute `height` exactly one more than the `height` of the document being chained to.\n\nIF any of these validations fail, then the entire sequence of documents is INVALID.\nNot just the current document."
16601660
},
16611661
"collaborators": {
1662-
"description": "A list of collaborators who may also publish updates to versions of this document.\nThis should include all parties who have not signed this document directly.\n\nEvery subsequent version can amend the collaborators list.\nHowever, the initial Author can never be removed from being able to\npublish a new version of the document.",
1662+
"description": "A list of collaborators who may be associated with this document.\n\n**Important**: For Conditions documents, only the original author can update and sign new versions.\nCollaborators listed here do not have permission to publish updates to this document.\nThis field is optional and may be used for documentation or organizational purposes only.",
16631663
"format": "Collaborators Reference List",
16641664
"required": "optional",
1665-
"validation": "This list does not imply these collaborators have consented to collaborate, only that the author/s\nare permitting these potential collaborators to participate in the drafting and submission process.\nHow collaborators are counted on a final submission is determined by a parameter defined at the\nBrand/Campaign/Category level (parameter name TBD). \nDepending on that configuration:\n\n* All listed collaborators may be required to submit a `final` Submission Action in addition\n to the author; **OR**\n* Only collaborators who submit a `final` Submission Action for the referenced version are\n included as collaborators on that submission.\n\nIf the parameter is not present, default to the latter mode (only final-signing collaborators are\nincluded).\nIn all modes a document is only considered final when the original author has submitted `final`.\n\nIn the event there are **MULTIPLE** `collaborators` listed, they **MUST** be sorted.\n\nSorting for each element of `collaborators` follows the same sort order as specified for Map Keys, \nas defined by CBOR Deterministic Encoding (4.3.2 Length-First Map Key Ordering)."
1665+
"validation": "For Conditions documents, collaborators do not have update permissions.\nOnly the original author can create new versions of Conditions documents.\n\nIn the event there are **MULTIPLE** `collaborators` listed, they **MUST** be sorted.\n\nSorting for each element of `collaborators` follows the same sort order as specified for Map Keys, \nas defined by CBOR Deterministic Encoding (4.3.2 Length-First Map Key Ordering)."
16661666
},
16671667
"id": {
16681668
"description": "Document ID, created the first time the document is created.\nThis must be a properly created UUIDv7 which contains the\ntimestamp of when the document was created.",
@@ -2759,7 +2759,7 @@
27592759
"validation": "In addition to the validation performed for `Document Reference` type fields: \n\n* Any linked referenced document that includes a `parameters` metadata must match the \n`parameters` of the referencing document,\nor a parent of those `parameters`.\n\nFor example, a linked reference to `Contest Parameters` is transitively a reference to\nthe Parameters document it references, and each parameters document they reference \nuntil the `Brand` parameters document is reached.\n\nThe use case here is for Templates.\nThe profile template, or proposal templates could be defined at any of these\nlevels, and as long as they all refer to the same chain of parameters in the\nhierarchy they are all valid."
27602760
},
27612761
"conditions": {
2762-
"description": "An array of references to all Conditions documents that the user has accepted.\n\nMust include ALL conditions required by the parameter hierarchy (Brand → Campaign → Category → Contest).\nThe act of listing these references and signing the document serves as the user's digital signature and acceptance.\n\n**Schema-level requirement**: This field is marked as optional in the schema, allowing documents to be created without it.\n\n**Validation-level requirement**: During validation, this field becomes required when the parameter hierarchy specifies conditions.\nIf conditions are required by any level in the parameter hierarchy (Brand, Campaign, Category, or Contest),\nthe field must be present and must exactly match all required conditions. If no conditions are specified\nin the parameter hierarchy, the field may be omitted.",
2762+
"description": "An array of references to all Conditions documents that the user has accepted.\n\nMust include ALL conditions required by the parameter hierarchy (Brand → Campaign → Category → Contest).\nThe act of listing these references and signing the document serves as the user's digital signature and acceptance.\n\n**Schema-level requirement**: This field is marked as optional in the schema, allowing documents to be created without it.\n\n**Validation-level requirement**: During validation, this field becomes required when the parameter hierarchy specifies conditions.\nIf conditions are required by any level in the parameter hierarchy (Brand, Campaign, Category, or Contest),\nthe field must be present and must exactly match all required conditions. If no conditions are specified\nin the parameter hierarchy, the field may be omitted.\n\n**Drafts Requirement**: Conditions must be included on every submission, including draft versions of proposals or other documents.\nThis ensures positive and current assent at every stage of document creation. Without this requirement, a user could accept\nthe terms for the first draft, change their mind, and then submit a subsequent draft without the terms, meaning their\nassent is no longer positively asserted. It also ensures that rules, such as those against objectionable material, apply\nto the document at every stage of its creation.\n\n**Collaborators Exclusion**: The acceptance of terms is tied to the act of submission by an individual. The terms and conditions\napply only to the individual who signs and submits the document. Collaborators listed on the document are not required to\naccept the conditions. This mirrors how contracts typically work, where each party must sign individually. Only the document\nauthor (signer) must include the `conditions` field to indicate their acceptance.",
27632763
"format": "Document Reference",
27642764
"required": "optional",
27652765
"multiple": true,
@@ -2908,7 +2908,7 @@
29082908
"validation": "In addition to the validation performed for `Document Reference` type fields: \n\n* Any linked referenced document that includes a `parameters` metadata must match the \n`parameters` of the referencing document,\nor a parent of those `parameters`.\n\nFor example, a linked reference to `Contest Parameters` is transitively a reference to\nthe Parameters document it references, and each parameters document they reference \nuntil the `Brand` parameters document is reached.\n\nThe use case here is for Templates.\nThe profile template, or proposal templates could be defined at any of these\nlevels, and as long as they all refer to the same chain of parameters in the\nhierarchy they are all valid."
29092909
},
29102910
"conditions": {
2911-
"description": "An array of references to all Conditions documents that the user has accepted.\n\nMust include ALL conditions required by the parameter hierarchy (Brand → Campaign → Category → Contest).\nThe act of listing these references and signing the document serves as the user's digital signature and acceptance.\n\n**Schema-level requirement**: This field is marked as optional in the schema, allowing documents to be created without it.\n\n**Validation-level requirement**: During validation, this field becomes required when the parameter hierarchy specifies conditions.\nIf conditions are required by any level in the parameter hierarchy (Brand, Campaign, Category, or Contest),\nthe field must be present and must exactly match all required conditions. If no conditions are specified\nin the parameter hierarchy, the field may be omitted.",
2911+
"description": "An array of references to all Conditions documents that the user has accepted.\n\nMust include ALL conditions required by the parameter hierarchy (Brand → Campaign → Category → Contest).\nThe act of listing these references and signing the document serves as the user's digital signature and acceptance.\n\n**Schema-level requirement**: This field is marked as optional in the schema, allowing documents to be created without it.\n\n**Validation-level requirement**: During validation, this field becomes required when the parameter hierarchy specifies conditions.\nIf conditions are required by any level in the parameter hierarchy (Brand, Campaign, Category, or Contest),\nthe field must be present and must exactly match all required conditions. If no conditions are specified\nin the parameter hierarchy, the field may be omitted.\n\n**Drafts Requirement**: Conditions must be included on every submission, including draft versions of proposals or other documents.\nThis ensures positive and current assent at every stage of document creation. Without this requirement, a user could accept\nthe terms for the first draft, change their mind, and then submit a subsequent draft without the terms, meaning their\nassent is no longer positively asserted. It also ensures that rules, such as those against objectionable material, apply\nto the document at every stage of its creation.\n\n**Collaborators Exclusion**: The acceptance of terms is tied to the act of submission by an individual. The terms and conditions\napply only to the individual who signs and submits the document. Collaborators listed on the document are not required to\naccept the conditions. This mirrors how contracts typically work, where each party must sign individually. Only the document\nauthor (signer) must include the `conditions` field to indicate their acceptance.",
29122912
"format": "Document Reference",
29132913
"required": "optional",
29142914
"multiple": true,

0 commit comments

Comments
 (0)