Skip to content

Add documentation for RELATIONS list clarifying ontology design principles #10

@chigwell

Description

@chigwell

User Story
As a new contributor to the eknowledge project,
I want comprehensive documentation for the RELATIONS list in relations.py
so that I can understand the ontology design principles when adding or modifying relationships.

Background
The RELATIONS list in relations.py contains 50+ relationship types (e.g., has_property, derived_from, temporally_related_to) but lacks design context. Contributors extending this ontology may:

  • Misinterpret relationship scopes (e.g., confusing part_of vs belongs_to)
  • Introduce redundant relationships
  • Overlook hierarchical patterns (e.g., is_a vs subclass_of)

Current risks include inconsistent relationship additions and increased maintenance costs. The absence of design rationale forces contributors to reverse-engineer patterns from existing entries.

Acceptance Criteria

  • Modify relations.py to add a docstring directly above the RELATIONS list declaration
  • Docstring must include:
    • Purpose of the ontology (e.g., balancing general knowledge graphs vs domain-specific needs)
    • Hierarchy/nesting principles (e.g., why has_attribute and has_property are distinct)
    • Criteria for adding new relationships (e.g., "Avoid duplicating semantic scope of existing terms")
    • Examples of edge cases and how they were resolved (e.g., located_in vs contains)
  • Validate via:
    1. Docstring appears in code completion tools (VS Code/PyCharm)
    2. All examples in the docstring match actual RELATIONS entries
    3. pytest runs pass without modifications to test logic
    4. No markdown formatting – use standard Python docstring syntax

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions