Ontologies in Graphora

An ontology is a formal specification of the entities, relationships, and rules that define a domain of knowledge. In Graphora, ontologies serve as the blueprint for your knowledge graph, defining what types of entities can exist, what properties they can have, and how they can relate to each other.

Why Ontologies Matter

Ontologies provide several key benefits:

Structure: They define the schema for your knowledge graph
Validation: They ensure data consistency and quality
Inference: They enable logical reasoning about your data
Interoperability: They facilitate data sharing and integration

Ontology Structure in Graphora

A Graphora ontology is defined in YAML format and consists of two main components: version information and entity definitions (which include their relationships).

1. Version Information

Basic version information about the ontology:

version: 1

2. Entities

Definitions of the entity types in your domain, including their properties and relationships:

entities:
  Company:
    properties:
      name:
        type: string
        description: Name of the Company
        unique: true
        required: true
      cik:
        type: string
        description: Cusip Identifier for Company
        unique: true
    relationships:
      HAS_BUSINESS:
        target: Business
        cardinality: one_to_many
      HAS_RISK_FACTOR:
        target: RiskFactor
        cardinality: one_to_many

Each entity has:

A unique name (as the key in the entities dictionary)
A set of properties, each with:
- A type (string, integer, etc.)
- A description
- Optional constraints (unique, required, index)
A set of relationships to other entities, each with:
- A target entity type
- Optional cardinality specification
- Optional properties with constraints

Working with Ontologies in the Client Library

The Graphora client library provides methods for registering and retrieving ontologies:

Registering an Ontology

from graphora import GraphoraClient

# Initialize client with user ID (required)
client = GraphoraClient(
    base_url="https://api.graphora.io",
    user_id="your-user-id",  # Required for all API calls
    api_key="your-api-key"
)

# Load ontology from a file
with open("ontology.yaml", "r") as f:
    ontology_yaml = f.read()

# Register the ontology
ontology_response = client.register_ontology(ontology_yaml)
ontology_id = ontology_response.id

Retrieving an Ontology

# Get an ontology by ID
ontology_yaml = client.get_ontology(ontology_id)

# Save it to a file
with open("retrieved_ontology.yaml", "w") as f:
    f.write(ontology_yaml)

Best Practices for Ontology Design

When designing ontologies for Graphora, consider these best practices:

Start simple: Begin with the core entities and relationships, then expand
Use clear names: Choose descriptive, consistent names for entities and relationships
Define constraints: Use property constraints to ensure data quality
Document thoroughly: Include descriptions for entities, relationships, and properties
Test with real data: Validate your ontology with representative data samples

Complete Ontology Example

Here’s a complete example of a financial reporting ontology:

version: 1
entities:
  Metadata:
    properties:
      name:
        type: string
        description: Form13_2023
      type:
        type: string
        description: financial_report
      about:
        type: string
        description: Form 13 Annual report containing company's financial statements and operations
        index: true
      filingDate:
        type: string
        description: Date in YYYY-MM-DD format
      context:
        type: string
        description: Contains high level information about the document processed
        index: true
    relationships:
      ABOUT_COMPANY:
        target: Company
        cardinality: many_to_one
        properties:
          name:
            type: string
            description: since
            unique: true
            required: false
  Company:
    properties:
      name:
        type: string
        description: Name of the Company
        unique: true
        required: true
      cik:
        type: string
        description: Cusip Identifier for Company
        unique: true
    relationships:
      HAS_BUSINESS:
        target: Business
        cardinality: one_to_many
      HAS_RISK_FACTOR:
        target: RiskFactor
        cardinality: one_to_many
      HAS_LEGAL_PROCEEDING:
        target: LegalProceeding
        cardinality: one_to_many
      HAS_MINE_SAFETY:
        target: MineSafety
        cardinality: one_to_many
  Business:
    properties:
      description:
        type: string
        description: General business description (10 words max)
      seasonality:
        type: string
        description: Business seasonality patterns (10 words max)
      employees:
        type: integer
        description: Number of employees
      regulatoryEnvironment:
        type: string
        description: Regulatory framework description (10 words max)
    relationships:
      HAS_SEGMENT:
        target: BusinessSegment
        cardinality: one_to_many
      HAS_PRODUCT:
        target: Product
        cardinality: one_to_many
      HAS_COMPETITION:
        target: Company
        cardinality: many_to_many
      HAS_RAW_MATERIAL:
        target: RawMaterial
        cardinality: one_to_many
      HAS_INTELLECTUAL_PROPERTY:
        target: IntellectualProperty
        cardinality: one_to_many
  RiskFactor:
    properties:
      name:
        type: string
        description: Risk factor name (5 words max)
        unique: true
        required: true
      description:
        type: string
        description: General risk description (10 words max)
      potentialImpact:
        type: string
        description: Potential impact of the risk on business (10 words max)
      mitigationStrategy:
        type: string
        description: Risk mitigation strategy (10 words max)

This ontology defines entities like Metadata, Company, Business, and RiskFactor, along with their properties and relationships. Each property has a type, description, and optional constraints like unique, required, and index.

Next Steps

Learn about the Transformation process
Explore the Merging capabilities
Check out the Graph data model

Getting Started

Core Concepts

Ontology Editor

API Reference

Examples

Ontologies

Ontologies in Graphora

Why Ontologies Matter

Ontology Structure in Graphora

1. Version Information

2. Entities

Working with Ontologies in the Client Library

Registering an Ontology

Retrieving an Ontology

Best Practices for Ontology Design

Complete Ontology Example

Next Steps

​Ontologies in Graphora

​Why Ontologies Matter

​Ontology Structure in Graphora

​1. Version Information

​2. Entities

​Working with Ontologies in the Client Library

​Registering an Ontology

​Retrieving an Ontology

​Best Practices for Ontology Design

​Complete Ontology Example

​Next Steps

Ontologies in Graphora

Why Ontologies Matter

Ontology Structure in Graphora

1. Version Information

2. Entities

Working with Ontologies in the Client Library

Registering an Ontology

Retrieving an Ontology

Best Practices for Ontology Design

Complete Ontology Example

Next Steps