Skip to content

Unify encyclopedia identities and typed connections: people, authors, definitions, works and contextual examples #73

Closed

Description

@holden

Problem and intended outcome

The encyclopedia needs to represent words, meanings, people, works, events, definitions, quotations and interpretations without confusing their identities or duplicating them for each role. Ambrose Bierce is one person who can author definitions, author literary works, be the subject of a biography, and appear in attributed interpretations. A definition he wrote remains a definition; his biography remains about him; neither becomes a generic example.

Likewise, a contributor can propose Elon Musk as an example of a particular meaning of “egomaniac.” Musk already has a person entry. We need one attributed, reviewable connection visible from both pages, not a second Musk record or an unqualified assertion in his biography.

Build a durable identity and relationship contract, then prove it through a small complete implementation. Related to #72 (backbone correctness), #69 (original model), #70 (implementation). This issue expands #72's stable attachment work into a dedicated design and implementation milestone. It does not replace source-refresh, recovery or operational work in #72.

Current evidence and constraints

Inspected at commit a2ef867:

  • Sources.Person stores authors in people, with optional Wikidata ID and a single source association. It has no foreign-key connection to the encyclopedia identity.
  • Encyclopedia.Concept stores encyclopedia subjects with a required QID; its kinds are taxon, thing, other. Locally created works/events/concepts cannot rely on having a QID.
  • Lexicon.Entry represents source-published text with word/concept targets and one author. Authorship already exists and should be preserved, not replaced with an example edge.
  • Lexicon.Sense explicitly preserves source-specific meanings; sources meet through concepts. Retain this policy unless an explicit ADR changes it. Earlier conceptual sketches of a shared sense must not silently override it.
  • The unshipped community migration sketch requires a lexical subject, provides one concept field for the example object, and uses unchecked polymorphic vote targets. It cannot express the whole model below with enforced integrity.

Keep Phoenix, Ecto and Postgres. A graph database, universal ontology, fixed table count or wholesale rewrite is not required. Extensibility means a controlled way to add types and relationships, not permitting arbitrary strings between arbitrary rows.

Proposed conceptual model

1. Stable identities, separate roles

Object Identity responsibility Examples
Lexeme Language, lemma and grammatical identity; explicit variants egomaniac / English / noun
Source sense One source's meaning, with durable identity and revisions A WordNet sense; a Wiktionary sense
Entity A referent independent of any provider Bierce, Musk, an abstract practice, an organization, an event
Work / expression / publication Distinguish creative work from translation, edition and hosted manifestation as needed A dictionary, its edition, an artwork, a particular recording
Content item / passage Typed text or media with an addressable identity Definition, quotation, poem passage, image, article excerpt
Assertion An attributable relationship between addressable objects Authored by, defines, depicts, illustrates, satirizes

Use internal IDs that survive provider changes. External identifiers belong in a namespace-aware mapping, with provenance and reconciliation status. Labels, names, URLs and QIDs are not universal primary keys. One person may have many names, sources and roles; identical names do not prove identical people. Login accounts and bots are accountable actors, not automatically identical to public biography subjects.

An encyclopedia page is a view over an identity, not another identity. A word page, person page and work page use different sections while sharing the same underlying linked records.

2. Definitions and examples have different semantics

  • A definition is source-authored content describing a lexeme or source sense, with edition and provenance. Historical or satirical definitions retain their genre and era.
  • An example claim says an object illustrates a selected sense or concept. The illustrating object, target and claim are separate identities.
  • A biography is a publication about a person. The person is not their Wikipedia article.
  • A quote has a speaker/author attribution and a work/passage location. A later reader's claim that it illustrates a concept is separate.
  • A source's grammatical usage example remains source content. A community classification of a real person remains community interpretation.
  • A reader can see several source definitions without treating them as identical senses. Concept-level examples may surface through explicit sense-to-concept mappings; sense-specific examples do not automatically propagate to other senses.

3. Make relationships first-class, typed and contextual

An assertion needs:

Field group Required meaning
Endpoints Real foreign-key-backed subject and object identities
Predicate Registered, directional relation with allowed endpoint types and display labels
Attribution Who made the claim; distinguish original claimant, submitting account/bot and importing process
Evidence Zero or more explicit evidence records with supporting/contradicting role, source revision and passage/time locator; requirements vary by claim type
Context Structured qualifiers such as date interval, language, jurisdiction, fictional setting, passage or event; optional readable rationale
Lifecycle Revision, provenance, withdrawal/supersession and review history
Independent dimensions Editorial review state, source support, matching confidence and relevance votes; do not reduce them to one score

Predicate registry examples:

Predicate Subject → object Reverse page label
authored_by Work/content → person or organization Works / definitions authored
published_in Content → edition/publication Contents
defines Definition → lexeme/source sense Definitions
about Article → entity Articles about
depicts Artwork/image → entity Depictions
illustrates Artifact/event/entity → sense/concept Attributed examples
satirizes Work/passage → entity/concept Satirical treatments
participates_in Person/organization → event Participants
refers_to Source sense → entity/concept Words referring to this subject

Store one directional assertion and derive the inverse display; do not write an independently editable mirror edge. Do not infer same_as, synonymy, truth, endorsement, transitivity or clinical diagnosis from an example relationship. Each predicate explicitly declares any inverse, symmetry or traversal rules. Reject invalid endpoint combinations.

For contested characterizations, a source's saying something and the encyclopedia endorsing it are separate. “Contributor A classifies Musk as an example of this sense” must remain attributed on both pages. Acceptance for display is not a diagnosis or a declaration of objective truth.

4. Bierce: complete worked example

flowchart TD
  B["Person: Ambrose Bierce"]
  W["Work: The Devil's Dictionary"] -->|authored_by| B
  ED["Specific edition / source publication"] -->|edition_of| W
  D["Definition content: nepotism"] -->|authored_by| B
  D -->|published_in| ED
  D -->|defines| L["Lexeme: nepotism, English noun"]
  BIO["Biographical article"] -->|about| B
  SR["Imported record + revision"] -->|evidence_for| D
  U["Reader's interpretation claim"] -->|classifies| D
  U -->|as_satire_of| C["Concept: nepotism"]
Loading

The content is a source definition whether or not a reader later attaches it as satire. Do not manufacture a modern source-sense alignment from a historical headword. The author identity is shared with Bierce's biography. The original work, edition, digital transcription provider and import run have distinct identities/roles. Coauthors, translators, editors and uncertain attribution require role-aware credits, rather than adding one author column per future case.

5. Enforceable storage approach

Preferred design to evaluate in an ADR: a small addressable-object registry referenced by relationships, with one-to-one typed domain records for lexemes, senses, entities and content. Keep lexical/source-specific constraints in domain tables. A registry gives true relationship-target foreign keys without replacing the application with an EAV store.

  • Specify how registry kind and subtype existence are enforced transactionally and at the database boundary (including deferred constraint triggers if needed); a plain (type, id) pair is insufficient.
  • Give people a one-to-one link to an entity identity, or migrate author details to an entity-backed person subtype. Preserve existing author references through a compatibility stage.
  • Generalize existing concepts to local entity identity with optional external IDs; preserve QID lookups and taxon behavior.
  • Keep definitions typed; introduce explicit authorship roles and work/edition links while preserving imported provenance.
  • Assertions reference registered endpoints and predicates; evidence, credits and qualifiers support multiple records. Assertions needing votes or challenges must themselves be addressable through a constrained target mechanism.
  • Predicate domain/range rules need database-enforced validation as well as changesets, including direct/bulk writes.
  • Separate assertion identity from supporting evidence. Two sources can support the same proposition without losing their individual attribution or withdrawal history. Different claimants/contexts must not be collapsed by an overbroad unique index.
  • Use typed columns/related tables for contractual fields. JSONB is for versioned provider extras, not a hiding place for endpoint identity, moderation or meaning.
  • Bound and paginate incoming/outgoing traversal with indexes; no recursive “everything related” query on ordinary page load.

ADR must compare this approach with explicit typed relationship tables. Choose the smallest model that passes the use cases and integrity tests; the conceptual contract is mandatory, this exact schema is a recommendation.

Source responsibilities

Source/channel Supplies Must not automatically establish
WordNet Source senses/groups and typed lexical relationships Identity with every other dictionary meaning
Wiktionary / Kaikki Lexical attestations, source definitions, forms and usage Universal sense identity from row position
Wikidata External entity identifiers and qualified statements Sole eligibility for local encyclopedia identity
Wikipedia Versioned articles about subjects Person = article; every statement independently verified
Bierce / Johnson Authored historical text and source context A timeless consensus definition
ConceptNet, proposed Commonsense assertions with native relation and underlying dataset lineage Every edge is synonymy or independent corroboration
Artsy / catalogues, proposed Artwork records, credits and publication context That an artwork illustrates nepotism or another concept
Community / curator bots Proposed interpretations, evidence and relevance judgments Authority to rewrite source definitions or silently merge identities

Provider, author, publisher, submitter and importer are different roles. Attribution and permission to reproduce content are separate. Store license/rights at the relevant record/media level; rights changes can restrict display while preserving permissible identity and relationship metadata. “All sources” means a reviewed adapter contract for each source, not indiscriminate ingestion.

Wireframes — conceptual, not shipped UI

A. Word page: definitions and attributed examples

egomaniac                                      English · noun
Meanings: [Source A sense 1 ▾]

DEFINITIONS
Source A · edition/revision                   [Provenance]
  Definition text…                            [Author →]
Source B · distinct source account             [View sense]

ATTRIBUTED EXAMPLES for selected meaning
Elon Musk →                                   Person
  Proposed by contributor A · Disputed
  Rationale: …                                [Evidence 2]
  [View claim] [Relevant] [Not relevant] [Challenge]

[Suggest a connection]

B. Person page: one identity, distinct roles

Ambrose Bierce                                 Person
[Overview] [Works] [Definitions] [Connections]

OVERVIEW
Biographical content…                         [Sources]

DEFINITIONS AUTHORED
nepotism →   The Devil's Dictionary · edition…
…                                             [More]

WORKS
The Devil's Dictionary →                      Author

ABOUT THIS PERSON
Biographical article →                       Source/revision

INTERPRETATIONS
Attributed claims, if any                     [Review state]

C. Connection composer: deliberate endpoints and context

Connect [Existing object ▾]  [+ Create minimal object]
Object: [Search person, work, event, passage…]
Relation: [Illustrates ▾]    (valid types only)
Target: [Word sense / Concept ▾] [Choose exact target]
Context: [Event, time, passage, language…]
Rationale: [Why does this connection apply?           ]
Evidence: [+ Source + passage/timestamp]
Claimant: [Original author, if quoting a claim]
Submitted by: current account                 (recorded)

Preview: “A proposes X as an illustration of Y.”
[Submit for review]

D. Claim detail: same record from either endpoint

X — illustrates → Y
Attributed to A · submitted by B · Disputed
Context and rationale…
Evidence: [Support] [Counterevidence]
History: proposed → edited → reviewed
[Open X] [Open Y] [Challenge] [Revision history]

On narrow screens these sections stack; target identity, attribution and review state remain visible. Relevance votes never replace the evidence or source definition. Empty sections are omitted. Public displays and server-side actions enforce the same moderation visibility.

Use-case and edge-case matrix

All cultural classifications below are proposed test scenarios, not factual judgments about real people or artworks.

Case Objects and connection Required distinction
Bierce / nepotism Person authors a definition in an edition of a work Author identity also powers biography; definition is not an example
Musk / egomaniac Contributor proposes person as example of a source sense Attributed evaluation, evidence and disagreement; one person record
Nepotism / hiring decision Event illustrates a practice; relatives participate in event Family relationship alone does not establish preferential treatment
Artsy family portrait Catalogue describes artwork; curator links it to inherited privilege Depiction/interpretation separate; no automatic nepotism classification
Irony / meme Meme satirizes a situation; reviewer calls it coincidence instead Conflicting classifications remain inspectable
Alienation Painting evokes social estrangement; legal passage uses property sense No propagation across unrelated senses
Home Building is a residence; poem explores belonging; UI uses “Home” Shared spelling does not merge referents
Resilience Material experiment, ecosystem study, personal account Scientific evidence and metaphor have distinct contexts
Justice Court decision and opposing philosophical evaluations Legal outcome differs from “the outcome was just”
Metamorphosis Biological process, titled literary work, transformative sculpture Title match differs from depiction and metaphor
Bank River-bank photo and financial institution Sense disambiguation before attaching evidence
Apple / apple Organization, fruit concept, word forms Case/name similarity does not imply identity
Poem passage Passage illustrates nepotism and favoritism Store passage once; separate claims and rationales
Translated poem Translator, original author, translated expression Do not credit translation wording to original author alone
Reposted meme Same image appears at multiple URLs with changed caption Hosting copies versus materially different versions; origin may be unknown
Fictional character Character portrayed as egomaniacal in one adaptation Character, actor, adaptation and scene are distinct
Misattributed quote Claimed author later corrected Attribution revision does not destroy quote or retarget its interpretation
Multilingual term Two source senses map to a shared concept Concept examples may be shared; linguistic usage examples remain language-specific
Organization as author Institution publishes a report Creator is not required to be a natural person
Anonymous work Work lacks known author or external ID Valid local identity without invented attribution/QID
Same-name people Two authors share a name Disambiguate; merge only with evidence
Source withdrawal One of two supporting records is withdrawn Preserve history and remaining support; recompute current status
Entity split One mistaken combined person record becomes two Ambiguous attachments require review, never arbitrary reassignment
New future medium Interactive installation added later Add typed object/predicate support without rewriting existing claims

Lifecycle and invariants

  1. Stable IDs never acquire a different meaning due to source reorder. Retired records remain resolvable with history.
  2. Merges preserve aliases, provenance and old links; splits explicitly identify ambiguous attachments. Reversible editorial actions have audit trails.
  3. Import reruns cannot overwrite human rejection/confirmation. Source withdrawal and editorial review are independent states.
  4. Example claims may target local concepts without a dictionary word; words remain a primary navigation surface, not a required foreign key for every object.
  5. Every reverse page view reflects the same assertion, status and access policy. No public leakage through the opposite endpoint.
  6. Relation-type changes or target changes create revisions and trigger appropriate re-review; existing votes do not silently endorse a changed claim.
  7. Traversal is explicit and bounded. Showing related-concept material must label the path; it cannot masquerade as a direct example.
  8. Unknown is a valid state for authorship, matching and evidence. A source badge does not imply truth or reproduction rights.

Implementation sequence and acceptance criteria

A. Decide and specify

  • ADR: identity registry versus typed relationship tables, entity/person unification, source-specific sense policy, predicate rules and work/edition scope.
  • Document the assertion/evidence/actor contract and lifecycle, including disputed characterizations and account-versus-person identity.
  • Review wireframes using Bierce, nepotism, egomaniac, alienation and one new local artwork.

B. Migrate identities safely

  • Backfill author→entity connections from verified identifiers; ambiguous candidates enter a review report. No name-only automatic merges.
  • Preserve every existing definition's source, author and URL; prove Bierce's definitions and biography resolve to one person identity.
  • Create local entities without QIDs; adding an external identifier later leaves their IDs and attachments unchanged.
  • Enforce subtype/target integrity, namespace uniqueness, predicate compatibility and deletion policy in Postgres as well as Ecto.
  • Stage compatibility reads and compare counts/provenance before removing obsolete paths; publish rollback procedure.

C. Ship a narrow vertical slice

  • Word, person and work views expose typed incoming/outgoing connections with bounded pagination.
  • Authenticated contributor creates an attributed connection with exact target, rationale and evidence; reviewer accepts, disputes or rejects it.
  • One claim appears consistently from both endpoints; a challenge and revision are visible from both.
  • Definition authorship is navigable independently of cultural claims. Multiple authors/roles and unknown authors are supported.
  • Same artifact can support multiple distinct claims without duplication or overly broad uniqueness failures.

D. Prove durability, semantics and extensibility

  • Run meaningful integration tests for the matrix, prioritizing polysemy, Bierce dual role, contested person example, passage reuse and local identities.
  • Test refresh/reorder/withdrawal, entity merge/split and attribution correction; no silent semantic retargeting or loss of review decisions.
  • Test direct invalid writes, orphan targets, prohibited predicate endpoints, account/bot attribution and restricted-claim visibility from either endpoint.
  • Test claim edits and voting identity; popularity cannot mutate definition text or source support.
  • Add one previously unsupported object kind through the documented extension path, without redesigning existing data or using arbitrary unvalidated metadata.
  • Measure ordinary word/person page and incoming-edge queries on representative high-degree entities; establish budgets and indexes before broad rollout.
  • Run mix precommit for implementation changes; update model docs and replace the unshipped community sketch with the chosen contract.

Done means

We can answer what is this object, what role does it play here, what connects it to another object, who asserts that connection, in what context, and what happens when the evidence changes? Bierce's authorship, biography and definition content stay distinct yet navigable. New kinds of examples can be added through a constrained extension path, without corrupting the lexical backbone or pretending every relationship has the same meaning.

Activity

  1. holden commented on Sep 17, 2026

    @holden
    MemberAuthor

    Closing as absorbed by #74: its semantic contract, wireframes and use cases were the spec #74 implemented, and its "required decisions" were resolved in ADR 0001 (docs/adr/0001-encyclopedia-model.md). Nothing here remains that #74, #82 or #84 does not carry.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions