Skip to content

feat(docs): Added Conditions System Specification #683

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
nathanbogale wants to merge 9 commits into
base: main
Choose a base branch
from
Open

feat(docs): Added Conditions System Specification #683

nathanbogale wants to merge 9 commits into from

Conversation

@nathanbogale
Copy link
Contributor

@nathanbogale nathanbogale commented Dec 7, 2025 •
edited
Loading

This PR introduces a new Conditions System for decentralized, auditable tracking of user acceptance of terms and conditions across the Catalyst platform. The implementation adds:

New Document Type: Conditions

  • Document Type: Conditions (UUID: b664afc2-6472-4028-b90f-875bf6eefab8)
  • Purpose: Simple document type published by authoritative parties (admins) to define terms and conditions that users must accept
  • Content: Supports Markdown or HTML payload for rich formatting
  • Status: Marked as draft: true per requirements - development should NOT begin until formally released

New Metadata Field: conditions

A new metadata field that serves two distinct purposes:

  1. On Parameter Documents (Brand/Campaign/Category/Contest Parameters):

    • Lists required condition documents for that level
    • Optional field - if not present, no conditions are required

  2. On User-Submitted Documents (Proposals, Comments, etc.):

    • References all condition documents the user has accepted
    • Must include ALL conditions from the parameter hierarchy (Brand → Campaign → Category → Contest)
    • The act of listing these references and signing serves as the user's digital signature and acceptance

Validation Logic

  • Transitive Collection: System collects all required conditions from the parameter hierarchy
  • Perfect Match Validation: User document's conditions array must exactly match the union of all required conditions
  • Rejection Criteria: Documents are rejected if missing required conditions, including extra conditions, or referencing revoked/invalid conditions

Further Documentation: https://docs.google.com/document/d/1ZxCbAhtlADP9oDmQUiJ5wuM2dcP3NjOcRV-32yEQMAo/edit?usp=sharing

Related Issue: 342

Please confirm the following checks

  • My code follows the style guidelines of this project
  • I have performed a self-review of my code
  • I have commented my code, particularly in hard-to-understand areas
  • I have made corresponding changes to the documentation
  • My changes generate no new warnings
  • I have added tests that prove my fix is effective or that my feature works (N/A - specification only)
  • New and existing unit tests pass locally with my changes (N/A - specification only)
  • Any dependent changes have been merged and published in downstream module

@nathanbogale
feat(docs): Introduce conditions metadata field and Conditions docu…
5e62204 
…ment type:

- Added a new `conditions` metadata field to parameter documents and user-submitted documents, specifying required terms and conditions.
- Created a new Conditions document type to define terms users must accept before submitting documents, including validation rules and business logic for acceptance.
- Updated the `signed_doc.json` specification to include the new Conditions document type and its associated metadata.
- Enhanced documentation to clarify the role of conditions in the document submission process and validation requirements.
@nathanbogale
feat(docs): Add conditions field to specifications and documentation
721f7ec 
- Updated the documentation to include the new Conditions document type, detailing its purpose and validation requirements.
- Enhanced the types.md file to list the Conditions document type, ensuring clarity in the available document types.
@nathanbogale nathanbogale requested a review from stevenj December 7, 2025 11:54
@nathanbogale nathanbogale self-assigned this Dec 7, 2025
@nathanbogale nathanbogale added documentation Pull requests that update a documentation do not merge yet PR is not ready to be merged yet draft Draft labels Dec 7, 2025
stevenj
stevenj requested changes Dec 8, 2025
View reviewed changes
specs/signed_doc.json Outdated
"description": "Media Type/s allowed in the Payload",
"format": "Media Type",
"required": "yes",
"value": "text/markdown"
Copy link
Collaborator

@stevenj stevenj Dec 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we have markdown and html content types already defined. Should be one of those.

@nathanbogale
fix(docs): Restore Conditions system enhancements after rebase
9f080c3 
- Add conditions.cue definition file
- Enhanced conditions metadata field documentation
- Add Contest Parameters to System Parameters list
- Support both Markdown and HTML content types with charset
- Update validation process to clarify upward traversal
- Add schema-level vs validation-level requirement distinction
@nathanbogale
fix(specs): Add Contest Parameters to System Parameters cluster in de…
35c14c2 
…fs.cue

- Add Contest Parameters to System Parameters docs array
- Update comment to reflect that Contest Parameters are included
- Aligns CUE definition with signed_doc.json specification
- Fixes inconsistency where JSON included Contest Parameters but CUE excluded it
@nathanbogale
fix(docs): Clarify Contest Parameters traversal paths in conditions v…
44942ae 
…alidation

- Replace ambiguous conditional description with explicit three-path specification
- Clearly describe traversal for Contest parented by Brand, Campaign, or Category
- Fixes potential implementation misinterpretation where conditional logic was embedded in linear description
- Updates validation descriptions in metadata.md, metadata.cue, and signed_doc.json
@nathanbogale
fix(docs): Clarify Contest Parameters parent determination in validation
f8b68a3 
- Add explicit instruction to examine Contest Parameters document's parameters field
- Add note explaining Contest can anchor to Brand, Campaign, or Category
- Clarify that validation must examine actual document, not assume fixed hierarchy
- Updates metadata.md, metadata.cue, and signed_doc.json for consistency
- Prevents implementation misinterpretation of flexible anchoring
@nathanbogale
fix(specs): Resolve collaborators field contradiction in Conditions d…
3a98a31 
…ocuments

- 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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@stevenj stevenj stevenj requested changes

Requested changes must be addressed to merge this pull request.

Assignees

@nathanbogale nathanbogale

Labels

do not merge yet PR is not ready to be merged yet documentation Pull requests that update a documentation draft Draft

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@nathanbogale @stevenj