​
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:

  1. Start simple: Begin with the core entities and relationships, then expand
  2. Use clear names: Choose descriptive, consistent names for entities and relationships
  3. Define constraints: Use property constraints to ensure data quality
  4. Document thoroughly: Include descriptions for entities, relationships, and properties
  5. 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