gh-greyhaven-ai-claude-code-config-grey-haven-plugins-developer-experience/skills/ontological-documentation/reference/ontology_patterns.md

Ontological Patterns in Software Documentation

This document describes common ontological patterns and taxonomies found in software systems for creating effective conceptual documentation.

Core Ontological Concepts

Fundamental Relationship Types

Is-A (Inheritance/Hyponymy)

• Description: A concept is a subtype or specialization of another concept
• Example: User is-a Person, Manager is-a Employee
• Code pattern: Class inheritance, interface implementation
• Documentation: Use "extends," "inherits from," "is a type of"

Part-Of (Mereology/Composition)

• Description: A concept is a component or constituent of another concept
• Example: Wheel is-part-of Car, Method is-part-of Class
• Code pattern: Object composition, nested classes, containment relationships
• Documentation: Use "contains," "comprises," "consists of"

Instance-Of (Instantiation)

• Description: An object is an instance of a concept/class
• Example: john_doe is-instance-of User, order_123 is-instance-of Order
• Code pattern: Object creation, variable assignment
• Documentation: Use "instance of," "example of," "specific case of"

Depends-On (Dependency)

• Description: A concept requires or relies on another concept
• Example: OrderService depends-on PaymentGateway, Controller depends-on Service
• Code pattern: Import statements, dependency injection, method calls
• Documentation: Use "requires," "uses," "relies on"

Associates-With (Association)

• Description: A concept has a loose semantic connection to another concept
• Example: User associates-with Order, Product associates-with Category
• Code pattern: Foreign keys, bidirectional references, event subscriptions
• Documentation: Use "related to," "connected with," "associated with"

Common Software Ontology Patterns

Layered Architecture Pattern

Presentation Layer
├── Controllers
├── Views
└── ViewModels

Business Logic Layer
├── Services
├── Domain Models
└── Business Rules

Data Access Layer
├── Repositories
├── Data Mappers
└── Database Models

Infrastructure Layer
├── External APIs
├── Message Queues
└── File Storage

Relationships:

• Controllers depend-on Services
• Services depend-on Repositories
• Repositories depend-on Database Models
• ViewModels part-of Presentation Layer

Domain-Driven Design Pattern

Entities: Objects with distinct identity

• Customer, Order, Product

Value Objects: Objects defined by their attributes

• Address, Money, DateRange

Aggregates: Clusters of domain objects

• OrderAggregate contains Order, OrderLine, OrderStatus

Repositories: Collections of aggregate roots

• CustomerRepository, OrderRepository

Domain Services: Business logic that doesn't fit in entities

• PaymentService, ShippingService

MVC Pattern Ontology

Model
├── Entity Models
├── View Models
└── Data Transfer Objects

View
├── Templates
├── Components
└── Layouts

Controller
├── Action Methods
├── Route Handlers
└── API Endpoints

Relationships:

• Controllers manipulate Models
• Controllers select Views
• Views display Models
• Models notify Views of changes

Microservices Pattern Ontology

Service Categories:

• API Gateway: Entry point for external requests
• Core Services: Business logic services
• Supporting Services: Shared functionality (auth, logging)
• Data Services: Database operations

Service Relationships:

• API Gateway routes-to Core Services
• Core Services call Supporting Services
• Services publish-to Message Broker
• Services read-from Configuration Service

Taxonomy Classification Systems

Functional Classification

By Purpose:

• Business Logic Components
• Data Management Components
• Presentation Components
• Integration Components
• Infrastructure Components

By Lifecycle:

• Singleton Components
• Scoped Components
• Transient Components
• Request-scoped Components

Structural Classification

By Abstraction Level:

• Interface Layer (highest abstraction)
• Service Layer
• Repository Layer
• Data Layer (lowest abstraction)

By Coupling:

• Tightly Coupled Components
• Loosely Coupled Components
• Decoupled Components

Documentation Templates

Concept Documentation Template

# [Concept Name]

## Definition
Brief, clear definition of the concept

## Purpose
Why this concept exists and what problem it solves

## Characteristics
Key attributes and properties of the concept

## Relationships
- **Is-A**: [Parent concepts]
- **Part-Of**: [Containing concepts]
- **Depends-On**: [Required concepts]
- **Associates-With**: [Related concepts]

## Examples
Concrete examples of the concept in use

## Implementation Notes
Technical implementation details and considerations

Relationship Documentation Template

# [Relationship Type]: [Source] → [Target]

## Relationship Description
Description of the semantic relationship

## Cardinality
- One-to-One, One-to-Many, Many-to-Many
- Required vs Optional

## Constraints
Rules and limitations on the relationship

## Implementation
How the relationship is implemented in code

## Examples
Specific examples of the relationship

Ontology Validation Rules

Consistency Rules

1. No Circular Inheritance: A class cannot inherit from itself (directly or indirectly)
2. Complete Relationships: All referenced concepts must be defined
3. Consistent Naming: Use consistent terminology throughout the ontology
4. Proper Abstraction Levels: Related concepts should be at similar abstraction levels

Completeness Rules

1. Defined Concepts: All concepts must have clear definitions
2. Documented Relationships: All relationships should be explicitly documented
3. Coverage: Important domain concepts should be represented
4. Hierarchy: Concepts should be organized in logical hierarchies

Best Practices

1. Use Standard Terminology: Prefer established domain vocabulary
2. Avoid Ambiguity: Define terms clearly and consistently
3. Maintain Separation: Separate conceptual models from implementation details
4. Document Rationale: Explain why certain relationships exist
5. Regular Review: Update ontology as system evolves