oneie
Version:
Build apps, websites, and AI agents in English. Zero-interaction setup for AI agents (Claude Code, Cursor, Windsurf). Download to your computer, run in the cloud, deploy to the edge. Open source and free forever.
311 lines (263 loc) • 9.54 kB
Markdown
# Verify Relationships Against Ontology
**Category:** ontology
**Version:** 1.0.0
**Used By:** agent-backend, agent-quality, agent-integrator
## Purpose
Validates proposed connection types and relationship structures against the ONE Ontology to ensure they follow established patterns, prevent invalid relationships, and maintain data integrity.
## Inputs
- **connectionType** (string): The type of connection (e.g., "authored", "owns", "contains")
- **sourceEntityType** (string): Type of source entity
- **targetEntityType** (string): Type of target entity
- **metadata** (object, optional): Additional relationship metadata
- **bidirectional** (boolean, optional): Whether relationship should work both ways. Default: false
## Outputs
- **isValid** (boolean): True if relationship is valid
- **errors** (array): Issues that prevent this relationship
- **warnings** (array): Potential problems or anti-patterns
- **recommendations** (array): Suggested improvements
- **alternativeConnections** (array): Other valid connection types for these entities
## Prerequisites
- Connection type follows naming convention (lowercase, underscores, verb-based)
- Source and target entity types exist in schema
- ONE ontology connection types documented in `/one/knowledge/ontology.md`
## Steps
1. **Load Known Connection Types**
- Read `/one/knowledge/ontology.md` for canonical connection types
- Load 25+ standard connection types:
- owns, authored, holds_tokens, enrolled_in, member_of
- follows, subscribed_to, attended, purchased
- contains, part_of, depends_on, related_to
- communicated, transacted, delegated, etc.
2. **Validate Connection Type Name**
- Check if connection type is known/standard
- If custom: Verify it's verb-based and descriptive
- Check for naming conflicts
- Warn if very similar to existing type
3. **Check Entity Type Compatibility**
- Verify source entity type exists
- Verify target entity type exists
- Check if relationship makes semantic sense
- Example: creator can "author" blog_post (valid)
- Example: blog_post cannot "author" creator (invalid - wrong direction)
4. **Validate Metadata Structure**
- Check metadata fields are appropriate for connection type
- Verify metadata types (string, number, boolean, object)
- Warn if metadata is too complex (should be flat when possible)
- Suggest moving complex data to separate entities
5. **Check for Anti-Patterns**
- **Circular Dependencies:** A → B → C → A
- **Self-References:** Entity connecting to itself (sometimes valid)
- **Many-to-Many without Junction:** Should use explicit join entities
- **Missing Timestamps:** validFrom/validTo for temporal relationships
- **Overly Generic:** "related_to" instead of specific relationship
6. **Verify Bidirectionality**
- If bidirectional=true, check if reverse makes sense
- Example: "follows" could be bidirectional (mutual follow)
- Example: "authored" should NOT be bidirectional (post can't author person)
- Suggest inverse relationship type if needed
7. **Check Index Requirements**
- Verify indexes exist for common queries
- by_source - Find all connections from entity
- by_target - Find all connections to entity
- by_type - Find all connections of specific type
- Compound indexes for scoped queries
8. **Suggest Alternative Connections**
- If current connection is invalid, suggest valid alternatives
- Example: Instead of "created" use "authored" for content
- Example: Instead of "has" use "owns" for ownership
9. **Generate Validation Report**
- Compile errors, warnings, recommendations
- Provide examples of correct usage
- Link to relevant documentation
## Examples
### Example 1: Valid Author Relationship
**Input:**
```json
{
"connectionType": "authored",
"sourceEntityType": "creator",
"targetEntityType": "blog_post",
"metadata": {
"role": "primary_author",
"contributionDate": 1697659200000
},
"bidirectional": false
}
```
**Output:**
```json
{
"isValid": true,
"errors": [],
"warnings": [],
"recommendations": [
"Consider adding validFrom/validTo for temporal tracking",
"Metadata looks good - role and date are appropriate"
],
"alternativeConnections": [
"created - Generic creation relationship",
"contributed_to - For co-authors"
]
}
```
### Example 2: Invalid Reverse Relationship
**Input:**
```json
{
"connectionType": "authored",
"sourceEntityType": "blog_post",
"targetEntityType": "creator",
"metadata": {},
"bidirectional": false
}
```
**Output:**
```json
{
"isValid": false,
"errors": [
"Semantic mismatch: blog_post cannot 'author' a creator",
"Relationship direction is reversed - should be creator -> blog_post"
],
"warnings": [],
"recommendations": [
"Reverse the direction: creator 'authored' blog_post",
"Or use different connection type if blog_post references creator"
],
"alternativeConnections": [
"authored_by - Inverse relationship (passive voice)",
"created_by - Generic inverse"
]
}
```
### Example 3: Circular Dependency Warning
**Input:**
```json
{
"connectionType": "depends_on",
"sourceEntityType": "service_a",
"targetEntityType": "service_b",
"metadata": {
"note": "service_b also depends on service_a creating a cycle"
},
"bidirectional": false
}
```
**Output:**
```json
{
"isValid": true,
"errors": [],
"warnings": [
"Potential circular dependency detected in metadata note",
"Circular dependencies can cause infinite loops - verify this is intentional"
],
"recommendations": [
"If mutual dependency is required, use explicit bidirectional flag",
"Consider refactoring to remove circular dependency",
"Add dependency_type metadata to distinguish hard vs soft dependencies"
],
"alternativeConnections": [
"communicates_with - For peer-to-peer relationships",
"integrated_with - For bidirectional integrations"
]
}
```
### Example 4: Custom Connection Type
**Input:**
```json
{
"connectionType": "peer_reviewed",
"sourceEntityType": "reviewer",
"targetEntityType": "research_paper",
"metadata": {
"reviewDate": 1697659200000,
"score": 8.5,
"comments": "Excellent methodology"
},
"bidirectional": false
}
```
**Output:**
```json
{
"isValid": true,
"errors": [],
"warnings": [
"Custom connection type 'peer_reviewed' is not in standard list",
"Consider using standard 'reviewed' connection type instead"
],
"recommendations": [
"Document this custom connection type in ontology",
"Metadata structure is good - score and comments are appropriate",
"Consider whether 'reviewed' standard type would work"
],
"alternativeConnections": [
"reviewed - Standard review relationship",
"evaluated - Generic assessment relationship",
"approved - If binary pass/fail"
]
}
```
### Example 5: Container Relationship
**Input:**
```json
{
"connectionType": "contains",
"sourceEntityType": "astro_page",
"targetEntityType": "react_component",
"metadata": {
"position": "center",
"order": 2
},
"bidirectional": false
}
```
**Output:**
```json
{
"isValid": true,
"errors": [],
"warnings": [],
"recommendations": [
"Perfect use of 'contains' for composition relationship",
"Metadata with position/order is good practice for layout",
"Consider adding inverse index for 'part_of' queries"
],
"alternativeConnections": [
"part_of - Inverse relationship (component part_of page)",
"includes - Similar to contains but less hierarchical"
]
}
```
## Error Handling
- **Unknown Entity Types:** Return error with list of valid entity types
- **Invalid Connection Type:** Suggest nearest valid connection type
- **Missing Required Metadata:** Specify what metadata is expected
- **Schema Mismatch:** Point to schema definition that conflicts
## Dependencies
- **Tools:** Read (for loading ontology docs), Grep (for searching connection types)
- **Skills:** `validate-schema.md` (to check if entities exist)
- **Docs:**
- `/one/knowledge/ontology.md` - Connection type catalog
- `https://docs.claude.com/en/docs/claude-code` - Claude Code docs (if needed)
## Tests
1. **Test Valid Standard Connection:** Verify known connection types pass
2. **Test Invalid Direction:** Verify reversed relationships are caught
3. **Test Custom Connection:** Verify custom types get warnings but pass
4. **Test Circular Dependency:** Verify cycles are detected
5. **Test Bidirectional Logic:** Verify bidirectional validation works
6. **Test Metadata Validation:** Verify complex metadata gets warnings
7. **Test Entity Type Checking:** Verify non-existent entities are caught
## Performance
- **Validation Time:** < 200ms per relationship
- **Caching:** Cache loaded connection types from ontology docs
- **Optimization:** Pre-load standard connection types at startup
## Lessons Learned
- **Verb-Based Names:** Connection types should be action verbs (authored, owns, contains)
- **Direction Matters:** Creator → Content (active voice) is clearer than Content → Creator
- **Metadata Should Be Flat:** Complex nested metadata belongs in separate entities
- **Temporal Relationships:** Most connections benefit from validFrom/validTo timestamps
- **Standard Over Custom:** Use standard connection types when possible for consistency
## Version History
- **1.0.0** (2025-10-18): Initial implementation with 25+ standard connection types