Logseq/Entity

• Logseq Entity

  • This page is the general conceptual model for entities in this knowledge garden: what an entity is, how a page is marked as one, and how entity definition pages are named. The entity definitions are child pages of this page.

  • Terms

    • Entity — a single thing that has its own page in the garden: one person, one software project, one book, etc. A page models one or more entities. When it models more than one, it must satisfy the shape requirements of each.
    • Entity definition — the documentation page for a category of entities that share the same modeling rules. Each entity definition page describes how to recognize, name, and create instances of that kind; individual pages that meet those rules are its instances. Each entity definition page is itself an entity, modeled by Logseq/Entity/Definition.

  • Entity and type

    • When you write about the entity system, call each thing an entity and each page that describes one an entity definition. Use type only to compare the entity system with a type system, as Software/Inheritance/Multiple/vs/Single does. When one entity descends from another, call them two entities in one lineage.
    • The entity system borrows ideas from type systems, and a page may differ from its entity definition while codekiln's idea of that entity is still changing. When codekiln first described the entity system in type-system terms, AI agents checked pages against their definitions like a type checker and asked "are you sure?" over every difference. codekiln brings pages into line with their definitions over time. An agent filing a new page follows its definition, and leaves an older page that differs as it was filed until codekiln asks for a change. Logseq/Entity/Article/Blog and Logseq/Entity/Podcast/Episode already say this about pages filed under older paths.

  • Finding the entity definitions

    • Each kind of entity has its own definition page under the Logseq/Entity/ namespace — one page per kind. The set of those pages is the list of entity definitions the garden models; there is no separate catalog to maintain on this page.
    • Every entity definition page carries logseq-entity:: [[Logseq/Entity/Definition]], so the list of entity definitions is the backlinks of Logseq/Entity/Definition — queryable rather than hand-maintained.
    • The first line under an entity definition page's heading is its short description, so the definition pages together read as a self-describing index.

  • How we mark a page as an entity

    • In frontmatter, add logseq-entity:: with a link to the entity definition page for each entity the page models.
    • When a page models a single entity, use one link: logseq-entity:: [[Logseq/Entity/Person]].
    • When a page models multiple entities, list them comma-separated, primary entity first: logseq-entity:: [[Logseq/Entity/Question]], [[Logseq/Entity/Card]]. The page must satisfy the shape requirements of all declared entities. Each entity definition page gets a backlink, so the instance appears in all relevant entity indexes.
    • Shared frontmatter conventions live on Logseq/Frontmatter.

  • Multiple entity membership

    • A page that declares two or more entities in logseq-entity:: is an instance of each. Its content must satisfy the shape requirements of all declared entity definitions.
    • The primary entity comes first in logseq-entity::. Ordering for a combination, and any combination-specific page shape, is documented on the primary entity's definition page.

  • Naming entity definition pages

    • All entity definition pages under Logseq/Entity/ use Title Case nouns. Multi-word names use nested namespace segments, for example Logseq/Entity/Software/Project.
    • Exception: tools and executables that are conventionally lowercase (e.g. tmux, git) may stay lowercase on their own topic pages, but entity definition pages are modeling nouns and use Title Case, for example Logseq/Entity/Person.
    • Do not use kebab-case segments (e.g. software-project, color-theme) for entity definition page names.
    • Plural or contextual reference forms belong in alias:: on the entity definition page when codekiln asks for them, per My/AI/Rule/Logseq/No Aliases Unless Asked; instance naming follows Logseq/Frontmatter/alias.