Skip to content

data.md

Latest commit

 

History

History
122 lines (79 loc) · 5.69 KB

data.md

File metadata and controls

122 lines (79 loc) · 5.69 KB

Data Structures

The Open Source Consent Package uses a set of core data structures designed for auditability, compliance, and flexibility. All type definitions are located in the packages/types directory.

Core Types Overview

ConsentRecord

Location: ConsentRecord.type.ts

The ConsentRecord is the central data structure representing a specific instance of consent given by a subject for a particular policy. Key characteristics:

  • Immutable: Once created, consent records are never modified; changes create new versions
  • Versioned: Each record has a version number for optimistic concurrency control
  • Auditable: Complete timestamp tracking of all consent decisions
  • Granular: Supports scope-based consent for different data categories

The record tracks not only what was consented to, but also who provided the consent (including proxy scenarios), when it was given, and comprehensive metadata for compliance purposes.

Key Relationships:

  • Links to a specific Policy via policyId
  • Contains granted and revoked scopes with individual timestamps
  • Supports proxy consent with relationship details and age group validation

Policy

Location: Policy.type.ts

Policies define what users are consenting to. The system supports:

  • Versioned Policies: Multiple versions of the same logical policy through policyGroupId
  • Rich Content: Structured content sections with HTML support
  • Scope Definitions: Available data categories that can be individually consented to
  • Lifecycle Management: Draft, active, and archived states

Policies are designed to be self-contained documents that fully describe what consent means for a particular use case, with built-in support for regulatory requirements like jurisdiction-specific rules.

Content Structure:

  • ContentSections: Structured sections (title, description, content) for presenting information
  • AvailableScopes: Granular data categories users can consent to individually
  • Metadata: Effective dates, jurisdiction, proxy requirements, etc.

Data Adapters

Locations:

The adapter interfaces define how the system interacts with different storage backends. This abstraction allows the same business logic to work with:

  • Cosmos DB: Production-ready cloud database
  • IndexedDB: Browser-based storage for offline/development scenarios
  • Custom adapters: Any storage system that implements the interface

Design Principles:

  • Storage Agnostic: Business logic doesn't depend on specific database features
  • Optimistic Concurrency: Version-based conflict resolution
  • Query Patterns: Designed around common consent management use cases

Input Types

Location: ConsentInputs.type.ts, PolicyInputs.type.ts

Input types define the data required to create new records. These are separate from the stored records to:

  • Exclude Generated Fields: IDs, timestamps, and version numbers are generated by the system
  • Validate Requirements: Ensure all necessary data is provided
  • Support Different Creation Patterns: Initial creation vs. version updates

Immutable Audit Trail

The system maintains complete audit trails through immutable, versioned records:

  1. Initial Grant: Creates version 1 with status 'granted'
  2. Scope Changes: New version with updated scopes, previous marked 'superseded'
  3. Revocation: New version with status 'revoked', previous marked 'superseded'
  4. Historical Access: All versions remain accessible for audit purposes

Granular Consent Management

Rather than all-or-nothing consent, the system supports:

  • Scope-Based Consent: Users can consent to specific data categories
  • Individual Timestamps: Each scope tracks when it was granted/revoked
  • Partial Revocation: Users can revoke specific scopes while maintaining others
  • Future Extensibility: New scopes can be added to existing policies

Proxy Consent Support

The system handles complex consent scenarios including:

  • Age-Based Rules: Different requirements for under-13, 13-17, and 18+ subjects
  • Relationship Tracking: Parent, guardian, researcher, etc.
  • Validation Logic: Ensures proxy consent is appropriate for the subject's age group
  • Audit Requirements: Full traceability of who provided consent on behalf of whom

Multi-Environment Flexibility

The adapter pattern enables:

  • Development: IndexedDB for local development without infrastructure setup
  • Testing: In-memory or file-based adapters for unit tests
  • Production: Cosmos DB for scalable, distributed storage
  • Hybrid: Different adapters for different environments or use cases

The architecture includes several technical safeguards:

  • Optimistic Concurrency: Prevents race conditions in consent updates
  • Input Validation: Type safety and runtime validation
  • Immutability: Prevents accidental modification of historical records
  • Separation of Concerns: Clear boundaries between different types of data

Usage Patterns

For detailed examples of how to work with these data structures, see:

The type definitions themselves include JSDoc comments explaining field purposes and constraints.