Onya 0.3.0

Knowledge graph (property graph-style) model and serialization for web resources

Onya is a knowledge graph expression and implementation. This repository combines a data model and format spec with a Python parser and API implementation.

Note: Using our provided onya-graph.SKILL.md with your favorite AI coding agent is a good way to automate Onya authoring and explore the format. Try providing a text document and asking it to generate a graph therefrom.

Python quick start

Installation

Requires Python 3.12 or later. The package is still in early development, so install directly from source:

git clone https://github.com/OoriData/Onya.git
cd Onya
pip install -U .

Command line tool

You can use the built-in CLI to export directly from an Onya Literate (.onya) file to the Mermaid diagram format:

onya convert test/resource/schemaorg/thingsfallapart.onya > out.mmd

Then use a site such as https://mermaid.live/ to generate a diagram such as:

Basic Python Usage

Here's a simple example demonstrating the core Onya API. First, let's define a small friendship graph in Onya Literate format:

# @docheader

* @document: http://example.org/friendship-graph
* @nodebase: http://example.org/people/
* @schema: https://schema.org/

# Chuks [Person]

* name: Chukwuemeka Okafor
* nickname: Chuks
* age: 28

# Ify [Person]

* name: Ifeoma Obasi
* nickname: Ify
* age: 27

Parse this graph and interact with it using the Python API.

from onya.graph import graph
from onya.serial.literate import LiterateParser

# Parse the Onya Literate text into a graph
onya_text = '''
# @docheader

* @document: http://example.org/friendship-graph
* @nodebase: http://example.org/people/
* @schema: https://schema.org/

# Chuks [Person]

* name: Chukwuemeka Okafor
* nickname: Chuks
* age: 28

# Ify [Person]

* name: Ifeoma Obasi
* nickname: Ify
* age: 27
'''

g = graph()
op = LiterateParser()
result = op.parse(onya_text, g)
doc_iri = result.doc_iri
print(f'Parsed document: {doc_iri}')
print(f'Graph has {len(g)} nodes')

# Access nodes and their properties
chuks = g['http://example.org/people/Chuks']
ify = g['http://example.org/people/Ify']

# Get a specific property value
for prop in chuks.getprop('https://schema.org/name'):
    print(f'Name: {prop.value}')

# Add a friendship edge between Chuks and Ify
friendship = chuks.add_edge('https://schema.org/knows', ify)
print(f'Added edge: {friendship}')

# Add nested properties to the friendship (metadata about the relationship)
friendship.add_property('https://schema.org/startDate', '2018-03-15')
friendship.add_property('https://schema.org/description', 'Met at university')

# Add a new property to Ify
ify.add_property('https://schema.org/jobTitle', 'Software Engineer')

# Modify a property by removing the old one and adding a new one
age_props = list(chuks.getprop('https://schema.org/age'))
for prop in age_props:
    chuks.remove_property(prop)
chuks.add_property('https://schema.org/age', '29')

# Traverse edges
for edge in chuks.traverse('https://schema.org/knows'):
    friend = edge.target
    for name_prop in friend.getprop('https://schema.org/name'):
        print(f'Chuks knows: {name_prop.value}')
    # Access nested properties on the edge
    for date_prop in edge.getprop('https://schema.org/startDate'):
        print(f'  Friends since: {date_prop.value}')

# Find all nodes of a certain type
for person in g.typematch('https://schema.org/Person'):
    for name_prop in person.getprop('https://schema.org/name'):
        print(f'Person in graph: {name_prop.value}')

# Reserialize to Onya literate
from onya.serial.literate import write

write(g)

This example demonstrates:

• Parsing Onya Literate format
• Accessing nodes and properties
• Adding edges with nested properties (reified relationships)
• Modifying properties
• Traversing the graph
• Querying by type

Visualization / export

Onya includes simple serializers to help you visualize graphs:

• Graphviz (DOT): from onya.serial import graphviz → graphviz.write(g, out=f) (see demo/graphviz_basic/)
• Mermaid (flowchart): from onya.serial import mermaid → mermaid.write(g, out=f) (see demo/mermaid_basic/; quick viewing via Mermaid Live Editor)

Command line tool

You can use the built-in CLI to export directly from an Onya Literate (.onya) file:

# Mermaid (default)
onya convert test/resource/schemaorg/thingsfallapart.onya > out.mmd

# Graphviz DOT
onya convert test/resource/schemaorg/thingsfallapart.onya --dot > out.dot

Acknowledgments

Onya is primarily developed by the crew at Oori Data. We offer LLMOps, data pipelines and software engineering services around AI/LLM applications.

Background

Onya is based on experience from developing Versa and also working on the MicroXML spec and implementations thereof.

The URL used for metavocabulary is managed via purl.org.

The name is from Igbo "ọ́nyà", web, snare, trap, and by extension, network. The expanded sense is ọ́nyà úchè, web of knowledge.

Contributing

Contributions welcome! We're interested in feedback from the community about what works and what doesn't in real-world usage. To get help with the code implementation, read CONTRIBUTING.md.

License

• Code (Python library): Apache 2.0 - See LICENSE
• Specification (wordloom_spec.md): Creative Commons Attribution 4.0 International (CC BY 4.0) - See LICENSE-spec

The specification is under CC BY 4.0 to encourage broad adoption and derivative work while ensuring attribution. We want the format itself to be as open and reusable as possible, allowing anyone to create implementations in any language or adapt the format for their specific needs.

Related Work

• networkx: Network Analysis in Python
• Apache AGE: PostgreSQL Extension that for graphs. ANSI SQL & openCypher over the same DB.