ActivityPub ontologies

In a previous example, we’ve seen how to extend ActivityPub types with dialects.

There is another method to dynamically extend defined types or to create new ones.

This method is based on ActivityPhp\Type\Ontology tool.

In this manual, we’ll only see basics of its API. For more practical aspects, there is a dedicated example in server’s part.



Create your ontology

Before creating your own ontology, keep in mind that ActivityPub already implements a lot of stuff. Check that they do not fit your needs before reinventing the wheel :)

In order to create a new ontology, you have to extend ActivityPhp\Type\OntologyBase class.

If you want to see a complete and working ontology, let’s see Peertube’s one.

Let’s define our simple ontology.

use ActivityPhp\Type\OntologyBase;

abstract class SimpleOntology extends OntologyBase
{
    /**
     * A definition of dialect to overload Activity Streams
     * vocabulary.
     * 
     * @var array
     */
    protected static $definitions = [
        'Group'  => ['myNewProperty'],
    ];
}

When a type (Group in previous example) does not exist, it is transparently created.


Add and load your ontology

After defining it, you have to load it.

use ActivityPhp\Type;
use ActivityPhp\Type\Ontology;


// Add and load this ontology
Ontology::add('simple-ontology', SimpleOntology::class);

// Now you can use this property
$group = Type::create('Group');
$group->myNewProperty = true;

Of course, you may accomplish that in a server context

use ActivityPhp\Server;

// Create a server instance and allow our simple ontology
$server = new Server([
    'ontologies' => [
        'simple-ontology' => SimpleOntology::class,
    ]
]);


Only add your ontology

It may be useful to add a set of dialects without allowing them.

It’s the role of the 3rd parameter. Ontology definitions are stacked, ready to be loaded but not usable.

use ActivityPhp\Type\Ontology;

// Add 2 definitions but don't load these dialects
Ontology::add('simple-ontology', SimpleOntology::class, false);

This way, your ontologies are configurable as plugins among contexts.

To complete this usage, you have a Ontology::load() method


Load a particular ontology

Based on previous example, you may now load specifically a particular ontology.


// Load only simple ontology
Ontology::load('mydialect1');

// Load all available ontologies
Ontology::load('*');


Unload ontologies

Sometimes, you need to keep only ActivityPub standard vocabulary.

You can unload ontologies.


// Unload only simple ontolgy
Ontology::unload('simple-ontology');

// Unload all available ontologies
Ontology::unload('*');


Contribute with your ontologies

This feature is made to ease implementation of major ontologies (Mastodon, Peertube, Pixelfed, etc…).

If you successfully implemented a new one, feel free to contribute with a pull request!

Edit this document on GitHub