Commonplace

Commonplace Data and Response Objects

For version 2 of the protocol.

Core Domain Objects

Card

A Card represents the complete, composed view of a card as exposed through the Commonplace Protocol. It combines information from multiple underlying storage objects to provide a unified interface for card operations.

Key Properties:

  • id: Stable identifier for this card (persists across versions)
  • name: Display name of the card
  • type_id: The Card Type that defines this card's structure and behavior
  • version: Current version number
  • fields: The card's field data organized by field name
  • created_at: When this card was originally created
  • updated_at: When this card was last modified
  • total_size_bytes: Total storage size of this card

Collection Context Properties:

  • reference_id: Unique identifier for this card's placement in the collection
  • collection_id: Which collection this card appears in
  • position: Spatial coordinates within the collection (x, y)
  • display_overrides: Collection-specific display customizations
  • reference_created_at: When this card was added to the collection

Metadata Properties:

  • reference_count: Total of references to this card
  • version_count: Total number of versions of this card
  • connections: Inter-card connections and relationships

Purpose: Card is the primary interface for all card operations in the protocol. It abstracts away the underlying storage decomposition while providing all information needed for display, editing, and manipulation.

Implementation Note: Cards are composed from multiple immutable storage objects but presented as a single coherent entity through the protocol.

Collection

A Collection represents rich metadata about a collection container, equivalent to a collection summary. It contains descriptive information and aggregate statistics but does not include actual content identifiers.

Key Properties:

  • id: Unique identifier for this collection
  • name: Display name of the collection
  • description: Optional description text
  • collection_type_id: Reference to the CollectionType that defines this collection's behavior
  • created_at: When this collection was created
  • updated_at: When this collection was last modified

Aggregate Properties:

  • total_card_count: Total number of cards (including in nested collections)
  • direct_card_count: Number of cards directly in this collection
  • child_collection_count: Number of direct child collections
  • total_size_bytes: Total storage size of all content
  • last_accessed: When this collection was last viewed or modified

Spatial Properties:

  • viewport_bounds: Default viewing area for this collection
  • spatial_layout_type: Type of spatial organization (grid, freeform, etc.)
  • default_zoom_level: Default zoom level for viewing this collection

Purpose: Collections provide rich metadata for organizational structure without carrying their actual contents, enabling efficient collection browsing and management.

CardType

A CardType defines the schema, behavior, and presentation template for cards of a specific type.

Key Properties:

  • id: Unique identifier for this card type
  • name: Human-readable name (e.g., "Note", "Task", "Person")
  • description: Description of this card type's purpose
  • version: Version of this card type definition
  • storage_schema_id: Reference to the underlying storage schema
  • created_at: When this card type was defined

Schema Properties:

  • fields: Field definitions with types, constraints, and validation rules
  • required_fields: List of fields that must have values
  • field_defaults: Default values for fields

Link Properties:

  • outlet: Single output link point for this card type
  • inlets: Array of input link points for this card type

Behavior Properties:

  • commonscript: Optional script code for validation and behavior
  • ui_template: Template for rendering cards of this type

Purpose: CardTypes define the structure and behavior of cards, serving as templates for card creation and validation.

CollectionType

A CollectionType defines the behavior, linking interface, and constraints for collections of a specific type.

Key Properties:

  • id: Unique identifier for this collection type
  • name: Human-readable name (e.g., "Workspace", "Project", "Kanban Board")
  • description: Description of this collection type's purpose
  • version: Version of this collection type definition
  • created_at: When this collection type was defined

Link Properties:

  • outlet: Single output link point for collections of this type
  • inlets: Array of input link points for collections of this type

Behavior Properties:

  • commonscript: Optional script code for collection-level validation and behavior
  • ui_template: Template for rendering collections of this type

Card Management Properties:

  • defined_card_types: CardTypes that are defined by this collection type
  • allowed_card_types: CardTypes that can be contained in collections of this type
  • card_type_constraints: Rules about which card types can coexist

Purpose: CollectionTypes define the structure, behavior, and constraints for collections, enabling typed collection hierarchies and link management.

Outlet

Defines the output link point for a card type or collection type.

Key Properties:

  • name: Identifier for this outlet (e.g., "output", "result")
  • description: Human-readable description of what this outlet provides
  • data_type: Optional type specification for data flowing through this outlet

Inlet

Defines an input link point for a card type or collection type, with optional type constraints.

Key Properties:

  • name: Identifier for this inlet (e.g., "input", "source", "trigger")
  • description: Human-readable description of what this inlet accepts
  • required: Whether this inlet must be linked for the entity to function
  • accepted_entity_types: Optional list of CardType or CollectionType IDs that can link to this inlet
  • data_type: Optional type specification for data this inlet accepts
  • multiple_links: Whether this inlet can accept multiple simultaneous links

Purpose: Inlets define typed link points that enable cards and collections to receive data or triggers from other entities, with optional type safety through entity type constraints.

Link

A Link represents a directed connection between two entities (cards or collections), enabling rich relationships and data flow within the Commonplace system.

Key Properties:

  • id: Unique identifier for this link
  • source: The entity that originates this link
  • target: The entity that receives this link
  • link_type: Type of relationship (e.g., "references", "depends_on", "contains")
  • parent_collection_id: The collection containing both linked entities (peer constraint)
  • created_at: When this link was established

Link Properties:

  • source_outlet: Named outlet point on the source entity
  • target_inlet: Named inlet point on the target entity
  • bidirectional: Whether this link operates in both directions
  • metadata: Additional key-value data about this relationship

Purpose: Links enable cards and collections to reference each other, creating networks of related information and enabling data flow between entities within the same collection context.

LinkEndpoint

Represents either end of a link, which can be either a card or a collection.

Endpoint Types:

  • Card: Link endpoint is a card
    • card_id: Identifier of the card
    • reference_id: Specific reference of the card within the collection
  • Collection: Link endpoint is a collection
    • collection_id: Identifier of the collection

Purpose: LinkEndpoint provides type-safe representation of link connections between different entity types while maintaining clear entity identification.

CardProxy

A CardProxy provides essential information about a card's placement within a collection, sufficient for rendering and interaction without including the full card data.

Key Properties:

  • reference_id: Unique identifier for this card reference
  • logical_card_id: Stable identifier for the underlying card
  • card_name: Display name of the card
  • schema_id: Card type identifier (for icons, styling, behavior)

Spatial Properties:

  • position: Coordinates within the collection (x, y)
  • display_overrides: Collection-specific display customizations
  • z_index: Layering order for overlapping cards

Metadata Properties:

  • last_updated: When this card was last modified
  • total_size_bytes: Storage size (for performance decisions)
  • link_count: Number of links involving this card
  • reference_created_at: When this card was added to the collection

Purpose: CardReferenceProxy enables collection content rendering and interaction without requiring full card data, supporting efficient large-collection operations.

Standard Response Patterns

SuccessResponse

A standardized success response for operations that don't return specific data.

Key Properties:

  • success: Always true for success responses
  • message: Optional human-readable success message
  • operation_id: Optional identifier for tracking the operation
  • timestamp: When the operation completed

ErrorResponse

A standardized error response providing detailed error information.

Key Properties:

  • success: Always false for error responses
  • error_code: Machine-readable error identifier
  • error_message: Human-readable error description
  • details: Optional additional error context
  • operation_id: Optional identifier for tracking the failed operation

CollectionContentsResponse

Response type for GetCollectionContents operations, containing collection content without full card data.

Key Properties:

  • collection_id: Which collection this response represents
  • cards: Array of CardProxy objects (actually References under the hood)
  • child_collections: Array of Collection objects (full metadata)
  • pagination_info: Information about result pagination

Pagination Properties:

  • offset: Starting position for offset-based pagination
  • limit: Maximum number of items returned
  • total_count: Total number of items available
  • spatial_bounds: Viewport bounds for spatial queries
  • has_more: Whether additional items are available

PaginatedResponse

Generic wrapper for paginated results of any content type.

Key Properties:

  • items: Array of result items (type varies by operation)
  • offset: Starting position in the full result set
  • limit: Maximum number of items in this response
  • total_count: Total number of items available across all pages
  • has_more: Whether additional pages are available

Server and Connection Types

ServerInfo

Information about the Commonplace server instance and its capabilities.

Key Properties:

  • server_name: Human-readable server identifier
  • server_version: Server software version
  • protocol_version: Supported protocol version
  • max_message_size: Maximum message size in bytes
  • capabilities: Server feature capabilities

ServerCapabilities

Detailed information about server features and limits.

Feature Flags:

  • supports_spatial_queries: Whether spatial collection queries are supported
  • supports_scripting: Whether CommonScript execution is available
  • supports_bulk_operations: Whether bulk transaction operations are supported
  • supports_real_time_sync: Whether real-time synchronization is available

Limits:

  • max_card_size_bytes: Maximum size for individual cards
  • max_collection_depth: Maximum nesting depth for collections
  • max_cards_per_collection: Maximum cards allowed in a single collection
  • query_timeout_seconds: Maximum time allowed for query operations

ConnectionInfo

Information about the current client connection.

Key Properties:

  • connection_id: Unique identifier for this connection
  • client_address: Client IP address and port
  • connected_at: When this connection was established
  • last_activity: Timestamp of last message received
  • session_id: Associated session identifier (if authenticated)

SessionInfo

Information about the authenticated session.

Key Properties:

  • session_id: Unique session identifier
  • user_id: Authenticated user identifier
  • container_id: Primary container for this session
  • created_at: When this session was created
  • expires_at: When this session expires
  • permissions: Access control permissions for this session

Query and Filter Types

CardQuery

Query specification for finding cards within collections.

Key Properties:

  • collection_id: Which collection to search in
  • search_scope: How deeply to search in collection hierarchy
  • schema_ids: Optional list of card types to include
  • field_filters: Filters on specific field values
  • text_search: Full-text search across card content
  • spatial_bounds: Spatial area to search within
  • date_range: Filter by creation or modification date

Result Control:

  • sort_criteria: How to order results
  • limit: Maximum number of results to return
  • offset: Starting position for pagination

CollectionQuery

Query specification for finding collections.

Key Properties:

  • parent_collection_id: Parent collection to search within
  • search_scope: How deeply to search in collection hierarchy
  • name_pattern: Pattern matching for collection names
  • collection_types: Types of collections to include
  • size_range: Filter by card count or storage size
  • date_range: Filter by creation or modification date

SpatialQuery

Query specification for spatial operations within collections.

Key Properties:

  • bounds: Rectangular area to query (x, y, width, height)
  • zoom_level: Level of detail for the query
  • include_partially_visible: Whether to include items partially within bounds
  • sort_by_distance: Whether to sort results by distance from center

Advanced Properties:

  • link_filter: Filter by link relationships
  • clustering_level: Level of spatial clustering to apply

FilterCriteria

Generic filter specification for field-based filtering.

Field Filters:

  • field_name: Name of field to filter on
  • operator: Comparison operator (equals, contains, greater_than, etc.)
  • value: Value to compare against
  • case_sensitive: Whether text comparisons are case-sensitive

Logical Operators:

  • and_filters: All conditions must match
  • or_filters: Any condition can match
  • not_filters: Conditions that must not match

SortCriteria

Specification for result ordering.

Key Properties:

  • field_name: Field to sort by
  • direction: Ascending or descending order
  • null_handling: How to handle null/missing values
  • secondary_sort: Additional sort criteria for tie-breaking

Special Sort Types:

  • spatial_distance: Sort by distance from a point
  • relevance_score: Sort by search relevance (for text queries)
  • connection_count: Sort by number of links
  • last_accessed: Sort by recent activity

SearchScope

Defines how deeply to search within collection hierarchies.

Scope Types:

  • DirectOnly: Search only the specified collection, no child collections
  • Recursive: Search the collection and all descendant collections (full tree)
  • OneLevel: Search the collection and immediate child collections only
  • MaxDepth(u32): Search to a specific depth level from the starting collection

Purpose: SearchScope provides precise control over hierarchical search operations, enabling both performance optimization and specific search patterns for different use cases.

Field Types and Constraints

FieldValue

A FieldValue represents the actual data stored in a card field, with strong typing to ensure data integrity.

Supported Types:

  • Text: String data with optional constraints
  • 'StyledText': String data representing rich text with formatting and styling (eg markdown)
  • Number: Numeric data (f64) with optional range constraints
  • 'Image': JPG, GIF, PNG images in binary
  • 'PDF': PDF documents in binary
  • 'Audio': Audio files in binary
  • 'Video': Video files in binary
  • 'Icon': Commonplace Vector Icon
  • 'File': Generic file uploads in binary
  • Boolean: True/false values
  • Date: ISO 8601 formatted date/time strings
  • CardReference: References to other cards by ID
  • List: Arrays of other FieldValues
  • Object: Nested key-value structures
  • 'Commonscript': Text representing Commonscript
  • Extension: Custom binary data with schema versioning

Purpose: FieldValues provide type-safe storage for all card content while supporting both simple and complex data structures.

FieldConstraints

Field constraints define validation rules and limits for field values.

Text Constraints:

  • min_length / max_length: Character count limits
  • pattern: Regular expression validation
  • allowed_values: Enumerated list of valid values

Number Constraints:

  • min_value / max_value: Numeric range limits
  • step: Required increment/decrement value
  • precision: Decimal place precision

General Constraints:

  • required: Whether field must have a value
  • unique: Whether field value must be unique within collection
  • indexed: Whether field should be indexed for fast queries

FieldType

Field type definitions specify the structure and constraints for card fields.

Core Properties:

  • name: Field identifier
  • field_type: The data type (Text, Number, Boolean, etc.)
  • required: Whether this field must have a value
  • constraints: Type-specific validation rules
  • default_value: Default value for new cards

Advanced Properties:

  • indexed: Whether to create search indexes
  • computed: Whether value is calculated from other fields

ValidationRules

Validation rules define complex constraints that span multiple fields or require custom logic.

Rule Types:

  • field_dependency: Rules about required field combinations
  • conditional_required: Fields required based on other field values
  • cross_field_validation: Rules comparing multiple field values
  • custom_script: CommonScript code for complex validation

Rule Structure:

  • rule_id: Unique identifier for this rule
  • description: Human-readable rule description
  • severity: Error, Warning, or Info level
  • trigger_conditions: When this rule should be evaluated

Metadata Types

Timestamps

Standardized timestamp information used throughout the system.

Key Properties:

  • created_at: When the object was originally created (Unix timestamp)
  • updated_at: When the object was last modified (Unix timestamp)
  • accessed_at: When the object was last accessed (Unix timestamp)
  • expires_at: Optional expiration timestamp

Format: All timestamps are Unix timestamps (seconds since epoch) for consistency and timezone neutrality.

VersionInfo

Information about object versioning and change history.

Key Properties:

  • current_version: Current version number
  • version_count: Total number of versions
  • last_modified_at: When the current version was created
  • last_modifier: Identifier of who made the last change
  • change_summary: Brief description of the most recent change

History Properties:

  • previous_version: Version number of the previous version
  • change_type: Type of change (create, update, migrate, etc.)
  • migration_info: Information about schema migrations (if applicable)

ReferenceMetadata

Metadata specific to card references within collections.

Key Properties:

  • reference_id: Unique identifier for this reference
  • collection_id: Which collection contains this reference
  • reference_created_at: When this reference was created
  • reference_updated_at: When reference metadata was last changed
  • position_history: Track of position changes over time

Display Properties:

  • custom_title: Collection-specific title override
  • custom_color: Collection-specific color override
  • visibility: Normal, minimized, or hidden status
  • local_tags: Collection-specific tags or labels

CollectionMetadata

Extended metadata for collections beyond basic properties.

Key Properties:

  • collection_type: Optional type classifier for collections
  • layout_preferences: Default layout and viewing preferences
  • access_patterns: Usage statistics and optimization hints
  • backup_info: Information about backups and snapshots

Performance Metadata:

  • cache_priority: Hint for memory management
  • index_status: Status of search indexes for this collection
  • compaction_info: Information about storage optimization
  • query_statistics: Performance data for query optimization

Identifier Types

UUID

All identifiers in the Commonplace system use RFC 4122 UUIDs for global uniqueness and collision resistance.

Properties:

  • Format: 128-bit UUID in standard hyphenated string format
  • Version: UUID version 4 (random) for most identifiers
  • Uniqueness: Globally unique across all Commonplace instances
  • Immutability: UUIDs never change once assigned

Usage: UUIDs are used for all primary identifiers (cards, collections, references, etc.) to support distributed operation and data migration.

CollectionId

Strongly-typed UUID specifically for collection identification.

Purpose: Identifies collections uniquely across the system, supporting hierarchical organization and cross-references.

CardId

Strongly-typed UUID for card identification, with distinction between logical and instance IDs.

Types:

  • logical_card_id: Stable identifier across all versions of a card
  • instance_id: Specific to individual card versions
  • reference_id: Specific to card placement within collections

Usage: Different ID types enable proper handling of card versioning, references, and collection placement.

CardTypeId

Strongly-typed UUID for card type/schema identification.

Purpose: Identifies card type definitions, enabling proper validation, rendering, and behavior for cards of specific types.

CollectionTypeId

Strongly-typed UUID for collection type/schema identification.

Purpose: Identifies collection type definitions, enabling proper validation, rendering, and behavior for collections of specific types.

Error and Status Types

ErrorCode

Machine-readable error codes for consistent error handling across clients.

Connection Errors:

  • INVALID_PROTOCOL_VERSION: Unsupported protocol version
  • CONNECTION_REFUSED: Server rejected connection
  • AUTHENTICATION_FAILED: Invalid credentials or expired session
  • SESSION_EXPIRED: Session timeout or invalidation

Request Errors:

  • INVALID_MESSAGE_FORMAT: Malformed message structure
  • UNKNOWN_MESSAGE_TYPE: Unsupported message type
  • MESSAGE_TOO_LARGE: Message exceeds size limits
  • RATE_LIMIT_EXCEEDED: Too many requests from client

Data Errors:

  • CARD_NOT_FOUND: Requested card does not exist
  • COLLECTION_NOT_FOUND: Requested collection does not exist
  • PERMISSION_DENIED: Insufficient permissions for operation
  • VALIDATION_FAILED: Data validation errors
  • SCHEMA_MISMATCH: Card data doesn't match expected schema

Server Errors:

  • INTERNAL_ERROR: Unexpected server error
  • SERVICE_UNAVAILABLE: Server temporarily unavailable
  • STORAGE_ERROR: Persistent storage failure
  • CAPACITY_EXCEEDED: Server resource limits exceeded

ValidationError

Detailed validation error information for data submission failures.

Key Properties:

  • field_name: Which field failed validation
  • error_type: Type of validation failure
  • error_message: Human-readable error description
  • expected_value: What value was expected (if applicable)
  • actual_value: What value was provided

Error Types:

  • REQUIRED_FIELD_MISSING: Required field not provided
  • INVALID_FORMAT: Field format doesn't match constraints
  • VALUE_OUT_OF_RANGE: Numeric value outside allowed range
  • REFERENCE_NOT_FOUND: Referenced object doesn't exist
  • CONSTRAINT_VIOLATION: Custom validation rule failed

OperationStatus

Status information for long-running or complex operations.

Key Properties:

  • operation_id: Unique identifier for tracking the operation
  • status: Current status (pending, in_progress, completed, failed)
  • progress_percent: Completion percentage (0-100)
  • estimated_completion: Estimated completion time
  • status_message: Current status description

Status Values:

  • PENDING: Operation queued but not yet started
  • IN_PROGRESS: Operation currently executing
  • COMPLETED: Operation finished successfully
  • FAILED: Operation failed with errors
  • CANCELLED: Operation was cancelled by user or system

ServerError

Detailed server error information for debugging and monitoring.

Key Properties:

  • error_id: Unique identifier for this error occurrence
  • error_code: Machine-readable error classification
  • error_message: Human-readable error description
  • timestamp: When the error occurred
  • context: Additional context about the error

Debug Information:

  • request_id: Associated request identifier
  • user_id: User associated with the error (if applicable)
  • stack_trace: Server-side stack trace (in development mode)
  • recovery_suggestions: Possible solutions or next steps