Folio: A Lexicon Suite for a Decentralized Reading Network

Introduction

This document outlines a suite of lexicons for "Folio," a decentralized application for tracking, reviewing, and discussing literature, akin to Good Reads. The design adheres to the principles of elegance and efficiency I previously detailed: atomicity, composability, user-centricity, and extensibility.

Design Philosophy

The Folio lexicons are designed to be:

Atomic: Each lexicon defines a single, discrete object or action. Composable: Lexicons are designed to reference each other, creating a rich, interconnected data graph. A review is linked to a book, which is linked to an author. User-Centric: The actions are intuitive and map directly to user behaviors. Extensible: The namespace com.folio is structured to allow for future feature additions without breaking changes.

The Lexicon Suite

1. com.folio.book

This is the core object, representing a single literary work.

{
  "lexicon": 1,
  "id": "com.folio.book",
  "defs": {
    "main": {
      "type": "record",
      "description": "A record of a single book.",
      "key": "tid",
      "record": {
        "type": "object",
        "required": ["title", "authorDid", "createdAt"],
        "properties": {
          "title": { "type": "string" },
          "subtitle": { "type": "string" },
          "authorDid": { "type": "string", "format": "did" },
          "summary": { "type": "string", "maxLength": 2000 },
          "cover": { "type": "blob", "accept": ["image/png", "image/jpeg"] },
          "isbn": { "type": "string" },
          "createdAt": { "type": "string", "format": "datetime" }
        }
      }
    }
  }
}

2. com.folio.shelf

This record represents a user's personal collection, tracking the status of books they own, are reading, or want to read.

{
  "lexicon": 1,
  "id": "com.folio.shelf",
  "defs": {
    "main": {
      "type": "record",
      "description": "An entry on a user's personal book shelf.",
      "key": "tid",
      "record": {
        "type": "object",
        "required": ["book", "status", "createdAt"],
        "properties": {
          "book": { "type": "string", "format": "at-uri" }, // links to com.folio.book
          "status": { "type": "string", "knownValues": ["to-read", "reading", "read", "on-hold"] },
          "createdAt": { "type": "string", "format": "datetime" }
        }
      }
    }
  }
}

3. com.folio.review

This lexicon allows users to post reviews and ratings for books.

{
  "lexicon": 1,
  "id": "com.folio.review",
  "defs": {
    "main": {
      "type": "record",
      "description": "A user's review of a book.",
      "key": "tid",
      "record": {
        "type": "object",
        "required": ["book", "rating", "createdAt"],
        "properties": {
          "book": { "type": "string", "format": "at-uri" }, // links to com.folio.book
          "rating": { "type": "integer", "minimum": 1, "maximum": 5 },
          "text": { "type": "string", "maxLength": 3000 },
          "createdAt": { "type": "string", "format": "datetime" }
        }
      }
    }
  }
}

4. com.folio.list

This allows for the creation of curated lists of books.

{
  "lexicon": 1,
  "id": "com.folio.list",
  "defs": {
    "main": {
      "type": "record",
      "description": "A curated list of books.",
      "key": "tid",
      "record": {
        "type": "object",
        "required": ["name", "books", "createdAt"],
        "properties": {
          "name": { "type": "string", "maxLength": 100 },
          "description": { "type": "string", "maxLength": 1000 },
          "books": { "type": "array", "items": { "type": "string", "format": "at-uri" } },
          "createdAt": { "type": "string", "format": "datetime" }
        }
      }
    }
  }
}

Conclusion

This suite provides a foundational layer for the Folio application. It is robust enough for core functionality while remaining flexible for future expansion, such as adding lexicons for discussions, author profiles, or social features.