[Feature Request]: Hierarchical Object Type System for AFFiNE

[vendelieu]

Description

Summary

This request proposes an architectural evolution for AFFiNE, transitioning from a flat tagging system to a Hierarchical Object Type System. This system allows users to define custom object types with structured properties, inheritance, and bidirectional relational linking. The primary goal is to provide a powerful, schema-driven environment while maintaining full backward compatibility with existing tags.

---

1. Motivation

Current Limitations

AFFiNE’s current tagging system uses simple string-based metadata. This presents several challenges for power users:

• Structural Deficit: Tags cannot represent complex entities (e.g., People, Projects, Meetings).
• Static Metadata: No mechanism exists to add custom properties like "Due Date" or "Email" to a tag.
• Unidirectional Data: Users cannot easily track relationships between different entities.
• Redundant Workflow: Lack of inheritance forces users to recreate similar structures manually.

User Stories

Researcher: "I want to create a 'Paper' type with properties like Authors, Publication Date, and DOI, so I can organize my literature systematically."

Project Manager: "I want Meeting notes to automatically show which Projects they relate to, without manually maintaining both directions."

---

2. Goals & Non-Goals

Goals

• G1: Define custom object types with typed properties.
• G2: Support single inheritance between object types.
• G3: Maintain 100% backward compatibility with existing tags.
• G4: Provide reactive, two-way relational linking.

Non-Goals

• NG1: Multi-inheritance (avoiding the "Diamond Problem" complexity).
• NG2: Computed/formula-based properties (slated for Phase 2).
• NG3: Type-level access control (relying on workspace-level permissions for now).

---

3. Architecture Overview

The system transitions the conceptual model from a flat "Tag" structure to a nested "Type" structure.

High-Level Approach

The core logic moves from Document → Tags to:

1. Document → Is an instance of → Object Type.
2. Object Type → Inherits from → Parent Type.
3. Document → References → Other Objects (via typed properties).

---

4. Core Concepts

Inheritance Model

Types support single inheritance. Child types inherit all properties from the parent, can "shadow" (override) them, or extend the schema with new fields.

Should prevent circular references (for example through DAG).

Example Hierarchy:

┌─────────────────┐
│    Document     │  ← Base system type
│  • title        │
│  • createdAt    │
└────────┬────────┘
         │ inherits
    ┌────┴────┬───────────┐
    ▼         ▼           ▼
┌───────┐ ┌───────┐ ┌──────────┐
│Article│ │ Note  │ │ Meeting  │
│• author│ │• mood │ │• attendees│
│• date  │ │       │ │• agenda  │
└───┬────┘ └───────┘ └──────────┘
    │ inherits
    ▼
┌─────────┐
│BlogPost │  ← Inherits from Article
│• slug   │     (has title, createdAt, author, date)
│• tags   │
└─────────┘

Property Types

The system supports a wide range of data primitives to ensure data integrity

Two-Way Linking (Backlinks)

When a property references another object, the system maintains a virtual backlink index. This allows a "Company" object to automatically list all "Employee" objects that point to it without manual entry.

---

5. User Experience

The Object Studio

A dedicated interface for managing the workspace "DNA." Users can:

1. Select a parent type (or start from a blank System Type).
2. Define metadata (Icons, Colors, Descriptions).
3. Add properties via a drag-and-drop schema builder.

Navigation Integration

The sidebar "Tags" section will be rebranded as Objects.

• Hierarchical View: Types are nested visually.
• Instance Counts: Real-time counters showing how many objects belong to a specific type.
• Quick Add: Create new instances directly from the sidebar.

▾ Objects
  ▾ 🏷️ Tag                    (12)
      ├── Work
      ├── Personal
      └── ...
  ▾ 👤 Person                  (5)
      ├── Alice
      ├── Bob
      └── ...
  ▸ 📁 Project                 (3)
  ▸ 📅 Meeting                 (0)

---

6. Migration & Security

Backward Compatibility

To ensure a smooth transition:

• System Tag Type: Existing tags are automatically mapped to a system:tag type.
• Lazy Migration: We will not perform a bulk database migration. Instead, data is "upgraded" to the new schema only when a user interacts with it.

Permissions

• Workspace Scope: Initially, all types are shared across the workspace.
• System Protection: Core types (Document, Tag, Media) are "locked" to prevent accidental deletion of essential infrastructure.

7. Open Questions

1. Versioning: How should we handle instances when a parent property is deleted? (Current plan: Keep data but hide from UI).
2. Cross-Workspace: Should users be able to export "Type Templates" to other workspaces?
3. Performance: How will the backlink index perform with >10,000 inter-connected objects?

Use case

No response

Anything else?

No response

Are you willing to submit a PR?

• Yes I'd like to help by submitting a PR!

[vendelieu]

I've tried to implement it somehow but with inconsistent success :)

[darkskygit]

the layered tag design may be very appealing to power users, but these concepts are quite complex for ordinary users and do not align with AFFiNE's design goals
I suggest you first submit an RFC describing how to provide this feature to advanced users without increasing the cognitive burden on ordinary users

[vendelieu]

I'm not highly experienced user of affine but tried my best to describe my vision of this.

TL;DR

• Replace flat tags with typed object schemas that support properties, inheritance, and relationships.
• Preserve AFFiNE’s simplicity via progressive disclosure and lazy migration.
• Tags remain tags by default; structure is opt-in, not mandatory.
• Introduce a dedicated Object Studio for schema management.
• Enable bidirectional links and data integrity without forcing database workflows.
• Maintain 100% backward compatibility.

---

Abstract

This RFC proposes the introduction of a Hierarchical Object Type System within the AFFiNE ecosystem. The system replaces the current flat, string-based tagging model with a schema-driven, inheritance-based object model while preserving AFFiNE’s core design principle of modesty. The proposal emphasizes progressive disclosure, backward compatibility, and minimal cognitive load for novice users, while enabling advanced relational modeling for power users.

---

Motivation

AFFiNE’s flat tag system works well for lightweight organization but does not scale to complex workflows requiring structured metadata, relationships, and consistency. As workspaces grow, users need to model real-world entities—people, projects, companies—using typed properties and links.

The challenge is enabling this power without compromising AFFiNE’s clean, low-friction writing experience.

---

Design Principles

1. Modesty First — No mandatory structure.
2. Progressive Disclosure — Reveal complexity only when needed.
3. Backward Compatibility — No breaking changes.
4. Predictability — Simple, visualizable data model.
5. Scalability — From notes to knowledge graphs.

---

Goals

• Typed object schemas
• Single-inheritance hierarchy
• Bidirectional relationships
• Optional, contextual UI exposure
• Dedicated schema management surface

---

Non-Goals

• Multiple inheritance
• Forced schema creation
• Early permission complexity
• Mandatory database-style workflows

---

Terminology

• Object Type: Schema definition
• Instance: Document conforming to a type
• System Type: Locked core type
• Object Studio: Schema management UI

---

Core Model

Conceptual Shift

flowchart LR
    A[Document] --> B[Tag]

Loading

becomes:

flowchart LR
    A[Document] -->|is-instance-of| B[Object Type]

Loading

Tags are lightweight object types with no required schema.

---

Inheritance Model

• Single inheritance only
• Tree structure
• Property inheritance is automatic
• Child types may extend or override

graph TD
    System[System Type]
    Person[Person]
    Client[Client]
    Contractor[Contractor]

    System --> Person
    Person --> Client
    Person --> Contractor

Loading

This avoids ambiguity and the diamond problem.

---

Property System

Supported Property Types

Type	Purpose
Text	General metadata
Number	Quantitative values
Date	Temporal data
Options	Controlled categories
Checkbox	Boolean state
Instance	Object reference
Backlink	Inverse reference

Relational Example

graph LR
    Project[Project]
    Company[Company]

    Project -->|Client| Company
    Company -->|Backlink| Project

Loading

Instance properties automatically generate backlinks, forming a navigable knowledge graph.

---

Progressive Disclosure Model

flowchart TB
    L1[Level 1: Basic Tags]
    L2[Level 2: Nested Tags]
    L3[Level 3: Properties]
    L4[Level 4: Object Studio]

    L1 --> L2 --> L3 --> L4

Loading

Levels

Level 1 — Basic Tagging
Simple #tag, mapped to system:tag. No UI change.

Level 2 — Nested Tags
Slash-based hierarchy, visual only. (for example #work/project)

Level 3 — Property Upgrade
Optional properties via simplified panel.

Level 4 — Full Schema Management
Inheritance and relationships via Object Studio.

---

User Interface

Object Studio

A dedicated “architect mode” for schema definition.

Capabilities

• Type hierarchy tree
• Property configuration
• Inheritance management
• Live instance preview

Separated from writing mode to prevent accidental complexity.

---

Contextual Properties

• Appear only when a document uses an object type
• Displayed in a collapsible Properties section
• Fully ignorable

Structured data never interferes with writing.

---

Migration Strategy

Backward Compatibility

• All existing tags map to system:tag
• No visible changes on rollout

Lazy Migration

• Tags upgrade only when modified
• No bulk migration
• Complexity scales per user need

---

System Types and Protection

Locked system types:

• Document
• Media
• Tag

These ensure workspace integrity.

---

Comparative Analysis

Logseq

• Split page/tag namespace
• Visual ambiguity

AFFiNE (Proposed)

• Unified object namespace
• Tags are lightweight objects
• One mental model

Tana

• Strong structural model
• Early enforcement

AFFiNE adopts the model but defers complexity via progressive disclosure.

---

Rollout Plan

Phase 1 — Foundation

• system:tag
• Experimental Object Studio
• Hidden Properties section
• Backlink indexing

Phase 2 — Relationships

• Inheritance
• Reactive schema updates
• Instance properties
• Hierarchical sidebar

Phase 3 — Automation

• Computed properties
• Type-level permissions
• Shared templates
• Advanced collections

---

Architectural Constraints

Constraint	Rationale
No circular inheritance	Prevents infinite resolution
Strict typing	Data integrity
Atomic updates	Consistency
Background reindexing	Performance

CRDT-based sync preserves collaborative intent.

---

Conclusion

This RFC introduces a structural upgrade to AFFiNE without sacrificing simplicity. By combining hierarchical object schemas with progressive disclosure, AFFiNE gains relational power while remaining approachable.

Structure emerges naturally, at the user’s pace—preserving AFFiNE’s identity as a modest, user-first knowledge tool.

[vendelieu]

Long story short that's how I see it

For simple users
“AFFiNE stays simple by default. Tags remain lightweight labels, writing stays distraction-free, and structure never gets in your way unless you ask for it.”
For experienced users
“When you need it, AFFiNE grows with you: tags become typed objects, properties add structure, and relationships form a navigable knowledge graph—without forcing complexity on day one.”

[darkskygit]

this idea is too broad and may require more discussion
i will move it to the discussions first to get more input from the community