Commonplace

Federation and Publishing

Commonplace allows you to share cards and collections across different instances through federation and publishing. This document explains how these features work and how you can use them to collaborate with others.

What is Federation?

Federation in Commonplace refers to the ability to share and synchronize cards and collections across different Commonplace instances. This allows:

  • Sharing knowledge with other users
  • Collaborating on shared collections
  • Publishing information for broader consumption
  • Subscribing to updates from other users

Federation is designed to give you control over what you share, how updates are handled, and who can access your information.

Card Sharing Modes

When sharing cards with other Commonplace instances, you can choose from several sharing modes:

Publish Mode

  • Shares the current version of a card only
  • No future updates are shared
  • Recipients can make their own changes locally
  • Useful for distributing stable, finished information

Feed Mode

  • Shares the current version plus all future updates
  • Changes you make are automatically sent to subscribers
  • Recipients can view but not modify the original
  • Recipients can create local derivatives with their own changes
  • Useful for ongoing information that you continue to update

Shared Mode

  • Collaborative mode where subscribers can edit
  • Subscriber edits create new versions in the original instance
  • All participants see all changes
  • Changes are attributed to their authors
  • Useful for collaborative projects and shared knowledge bases

Event-Driven Updates

Federation in Commonplace uses an event-driven system to propagate changes:

Event Generation

  • Card updates generate signed events
  • Events include metadata about the change
  • Events are cryptographically signed by the source instance

Event Delivery

  • Events are sent to subscribing instances
  • Store-and-forward system ensures reliable delivery
  • Events can be delivered even if recipients are offline

Event Content

  • Small updates include full card data in the event
  • Large updates use differential retrieval
  • Recipients can verify the authenticity of events using PKI

Collection Publishing

Collections can be published with the same modes as individual cards:

Collection-Level Sharing

  • Publishing a collection shares its properties and structure
  • The publishing mode applies to the collection and all contained cards
  • Nested collections can have their own publishing settings

Collection References

  • When a collection is published, subscribers receive references to it
  • These references maintain the connection to the source
  • Updates to the collection structure propagate according to the sharing mode

Security and Privacy

Federation includes several features to ensure security and privacy:

Authentication

  • Cryptographic signatures verify the source of shared cards
  • Public key infrastructure (PKI) establishes trust between instances
  • Recipients can verify that updates come from the original source

Authorization

  • Publishers control who can access their shared cards
  • Access can be granted to specific users or made public
  • Different sharing modes can be used for different recipients

Encryption

  • Sensitive information can be encrypted during transmission
  • End-to-end encryption protects content from intermediaries
  • Encryption keys can be managed to control access over time

Working with Federation

As you use Commonplace, you might use federation to:

  • Share research: Publish collections of research notes with colleagues
  • Collaborate on projects: Create shared collections for team projects
  • Publish knowledge: Create public feeds of information in your area of expertise
  • Subscribe to updates: Follow collections published by others in your field
  • Build networks: Connect your knowledge base to those of collaborators

These operations are covered in detail in the Sharing and Publishing document.

Next Steps

Now that you understand federation and publishing, you might want to learn about: