Querying and editing ontologies

The ontology object

Once a CowlOntology object has been read into memory, it can be queried and edited to retrieve, add, or remove axioms, annotations, and other constructs.

struct CowlOntology

Represents an Ontology in the OWL 2 specification.

Pseudo-extends: CowlObject

CowlManager *cowl_ontology_get_manager(CowlOntology *onto)

Gets the manager of this ontology.

Parameters:

  • onto – The ontology.

Returns:

The manager.

CowlSymTable *cowl_ontology_get_sym_table(CowlOntology *onto)

Gets the symbol table of this ontology.

Parameters:

  • onto – The ontology.

Returns:

The symbol table.

CowlOntologyId cowl_ontology_get_id(CowlOntology *onto)

Gets the ontology ID.

Parameters:

  • onto – The ontology.

Returns:

The ontology ID.

void cowl_ontology_set_iri(CowlOntology *onto, CowlIRI *iri)

Sets the IRI of the ontology.

Parameters:

  • onto – The ontology.

  • iri – The IRI.

void cowl_ontology_set_version(CowlOntology *onto, CowlIRI *version)

Sets the version IRI of the ontology.

Parameters:

  • onto – The ontology.

  • version – The version IRI.

CowlVector *cowl_ontology_get_annot(CowlOntology *onto)

Gets the annotations of the specified ontology.

Parameters:

  • onto – The ontology.

Returns:

The annotations.

cowl_ret cowl_ontology_add_annot(CowlOntology *onto, CowlAnnotation *annot)

Adds an annotation to the ontology.

Parameters:

  • onto – The ontology.

  • annot – The annotation.

Returns:

Return code.

void cowl_ontology_remove_annot(CowlOntology *onto, CowlAnnotation *annot)

Removes an annotation from the ontology.

Parameters:

  • onto – The ontology.

  • annot – The annotation.

CowlOntology *cowl_ontology_get_import(CowlOntology *onto, CowlIRI *iri)

Gets an imported ontology given its import IRI.

Parameters:

  • onto – The ontology.

  • iri – Import IRI.

Returns:

Imported ontology.

CowlIRI *cowl_ontology_get_import_iri(CowlOntology *onto, CowlOntology *import)

Gets the import IRI of an imported ontology.

Parameters:

  • onto – The ontology.

  • import – The imported ontology.

Returns:

Import IRI.

cowl_ret cowl_ontology_add_import(CowlOntology *onto, CowlIRI *import)

Adds an import to the ontology.

Parameters:

  • onto – The ontology.

  • import – IRI of the imported ontology.

Returns:

Return code.

void cowl_ontology_remove_import(CowlOntology *onto, CowlIRI *import)

Removes an import from the ontology.

Parameters:

  • onto – The ontology.

  • import – IRI of the imported ontology.

cowl_ret cowl_ontology_add_axiom(CowlOntology *onto, CowlAnyAxiom *axiom)

Adds an axiom to the ontology.

Parameters:

  • onto – The ontology.

  • axiom – The axiom.

Returns:

Return code.

void cowl_ontology_remove_axiom(CowlOntology *onto, CowlAnyAxiom *axiom)

Removes an axiom from the ontology.

Parameters:

  • onto – The ontology.

  • axiom – The axiom.

ulib_uint cowl_ontology_axiom_count(CowlOntology *onto, bool imports)

Gets the number of axioms in the ontology.

Parameters:

  • onto – The ontology.

  • imports – If true, the query recurses over imported ontologies.

Returns:

Number of axioms.

ulib_uint cowl_ontology_imports_count(CowlOntology *onto, bool imports)

Gets the number of imported ontologies.

Parameters:

  • onto – The ontology.

  • imports – If true, the query recurses over imported ontologies.

Returns:

Number of imports.

ulib_uint cowl_ontology_axiom_count_for_type(CowlOntology *onto, CowlAxiomType type, bool imports)

Gets the number of axioms of the specified type.

Parameters:

  • onto – The ontology.

  • type – The axiom type.

  • imports – If true, the query recurses over imported ontologies.

Returns:

Number of axioms.

ulib_uint cowl_ontology_axiom_count_for_primitive(CowlOntology *onto, CowlAnyPrimitive *primitive, bool imports)

Gets the number of axioms referencing the specified primitive.

Parameters:

  • onto – The ontology.

  • primitive – The primitive.

  • imports – If true, the query recurses over imported ontologies.

Returns:

Number of axioms.

ulib_uint cowl_ontology_primitives_count(CowlOntology *onto, CowlPrimitiveFlags flags, bool imports)

Gets the number of primitives.

Parameters:

  • onto – The ontology.

  • flags – Primitive flags.

  • imports – If true, the query recurses over imported ontologies.

Returns:

Number of primitives.

bool cowl_ontology_has_primitive(CowlOntology *onto, CowlAnyPrimitive *primitive, bool imports)

Checks if the specified primitive is referenced by an axiom in the ontology.

Parameters:

  • onto – The ontology.

  • primitive – The primitive.

  • imports – If true, the query recurses over imported ontologies.

Returns:

True if the primitive is referenced by an axiom, false otherwise.

bool cowl_ontology_has_axiom(CowlOntology *onto, CowlAnyAxiom *axiom, bool imports)

Checks whether the ontology contains the specified axiom.

Parameters:

  • onto – The ontology.

  • axiom – The axiom.

  • imports – If true, the query recurses over imported ontologies.

Returns:

True if the ontology contains the axiom, false otherwise.

bool cowl_ontology_iterate_primitives(CowlOntology *onto, CowlPrimitiveFlags flags, CowlIterator *iter, bool imports)

Iterates over the primitives referenced by the specified ontology.

Parameters:

  • onto – The ontology.

  • flags – Primitive flags.

  • iter – The iterator.

  • imports – If true, the query recurses over imported ontologies.

Returns:

True if the iteration was completed, false if it was stopped.

bool cowl_ontology_iterate_imports(CowlOntology *onto, CowlIterator *iter, bool imports)

Iterates over the imported ontologies.

Parameters:

  • onto – The ontology.

  • iter – The iterator.

  • imports – If true, the query recurses over imported ontologies.

Returns:

True if the iteration was completed, false if it was stopped.

bool cowl_ontology_iterate_import_iris(CowlOntology *onto, CowlIterator *iter, bool imports)

Iterates over the import IRIs.

Parameters:

  • onto – The ontology.

  • iter – The iterator.

  • imports – If true, the query recurses over imported ontologies.

Returns:

True if the iteration was completed, false if it was stopped.

bool cowl_ontology_iterate_axioms(CowlOntology *onto, CowlIterator *iter, bool imports)

Iterates over the axioms in the ontology.

Parameters:

  • onto – The ontology.

  • iter – The iterator.

  • imports – If true, the query recurses over imported ontologies.

Returns:

True if the iteration was completed, false if it was stopped.

bool cowl_ontology_iterate_axioms_of_type(CowlOntology *onto, CowlAxiomType type, CowlIterator *iter, bool imports)

Iterates over the axioms of a certain type.

Parameters:

  • onto – The ontology.

  • type – The axiom type.

  • iter – The iterator.

  • imports – If true, the query recurses over imported ontologies.

Returns:

True if the iteration was completed, false if it was stopped.

bool cowl_ontology_iterate_axioms_for_primitive(CowlOntology *onto, CowlAnyPrimitive *primitive, CowlIterator *iter, bool imports)

Iterates over the axioms referencing the specified primitive.

Parameters:

  • onto – The ontology.

  • primitive – The primitive.

  • iter – The iterator.

  • imports – If true, the query recurses over imported ontologies.

Returns:

True if the iteration was completed, false if it was stopped.

Iterates over the constructs that are related to the specified primitive by some axiom.

Parameters:

  • onto – The ontology.

  • primitive – The primitive.

  • type –

  • position – Position of the related constructs.

  • iter – The iterator.

  • imports – If true, the query recurses over imported ontologies.

Returns:

True if the iteration was completed, false if it was stopped.

bool cowl_ontology_iterate_sub_classes(CowlOntology *onto, CowlClass *owl_class, CowlIterator *iter, bool imports)

Iterates over the subclasses of the specified class.

Parameters:

  • onto – The ontology.

  • owl_class – The class.

  • iter – The iterator.

  • imports – If true, the query recurses over imported ontologies.

Returns:

True if the iteration was completed, false if it was stopped.

bool cowl_ontology_iterate_super_classes(CowlOntology *onto, CowlClass *owl_class, CowlIterator *iter, bool imports)

Iterates over the superclasses of the specified class.

Parameters:

  • onto – The ontology.

  • owl_class – The class.

  • iter – The iterator.

  • imports – If true, the query recurses over imported ontologies.

Returns:

True if the iteration was completed, false if it was stopped.

bool cowl_ontology_iterate_eq_classes(CowlOntology *onto, CowlClass *owl_class, CowlIterator *iter, bool imports)

Iterates over the equivalent classes of the specified class.

Parameters:

  • onto – The ontology.

  • owl_class – The class.

  • iter – The iterator.

  • imports – If true, the query recurses over imported ontologies.

Returns:

True if the iteration was completed, false if it was stopped.

bool cowl_ontology_iterate_disjoint_classes(CowlOntology *onto, CowlClass *owl_class, CowlIterator *iter, bool imports)

Iterates over the disjoint classes of the specified class.

Parameters:

  • onto – The ontology.

  • owl_class – The class.

  • iter – The iterator.

  • imports – If true, the query recurses over imported ontologies.

Returns:

True if the iteration was completed, false if it was stopped.

bool cowl_ontology_iterate_types(CowlOntology *onto, CowlAnyIndividual *ind, CowlIterator *iter, bool imports)

Iterates over the types of the specified individual.

Parameters:

  • onto – The ontology.

  • ind – The individual.

  • iter – The iterator.

  • imports – If true, the query recurses over imported ontologies.

Returns:

True if the iteration was completed, false if it was stopped.

struct CowlOntologyId

An object that identifies an ontology.

See also

Ontology IRI and version IRI

Public Members

CowlIRI *iri

The ontology IRI.

CowlIRI *version

The version IRI.

CowlOntologyId cowl_ontology_id_anonymous(void)

Creates the ID of an anonymous ontology.

Returns:

ID of an anonymous ontology.

bool cowl_ontology_id_equals(CowlOntologyId lhs, CowlOntologyId rhs)

Equality function.

Note

Ontology IDs are considered equal if they have the same ontology IRI and version IRI. Since OWL 2 allows for both the ontology and version IRIs to be simultaneously empty, in that case the ontology IDs are considered different unless they are the same instance.

Parameters:

  • lhs – LHS of the equality relation.

  • rhs – RHS of the equality relation.

Returns:

True if the equality relation holds, false otherwise.

ulib_uint cowl_ontology_id_hash(CowlOntologyId id)

Hash function.

Parameters:

  • id – The ontology ID.

Returns:

The hash value.

Querying ontologies

The base mechanism for querying a CowlOntology and other constructs is invoking their iterator member functions, which generally accept CowlIterator instances.

CowlIterator is a wrapper around a function that is called for every element matched by the query. By providing a generic context pointer, you can plug any custom data structure (loggers, collections, etc.), which allows for arbitrarily complex programmatic queries. Iteration can be stopped at any time, enabling early termination for queries such as finding the first construct that matches some condition.

struct CowlIterator

Iterator API.

A CowlIterator is a wrapper around a function that gets called for every element matched by a query. The context provided while creating the iterator is passed to the for_each function each time it is called.

The iterator function returns a bool that can be used to control iteration: by returning true iteration proceeds to the next element, while returning false causes it to stop.

Public Members

void *ctx

The iterator context, can be anything.

bool (*for_each)(void *ctx, CowlAny *object)

Pointer to a function called by the iterator for every element.

CowlIterator cowl_iterator_vec(UVec_CowlObjectPtr *vec, bool retain)

Initializes an iterator that stores objects in the specified vector.

Note

When using this iterator, iterator functions return false on error, e.g. when memory cannot be allocated.

Parameters:

  • vec – [out] Vector.

  • retain – If true, elements are retained.

Returns:

Initialized iterator.

CowlIterator cowl_iterator_set(UHash_CowlObjectTable *set, bool retain)

Initializes an iterator that stores objects in the specified set.

Note

When using this iterator, iterator functions return false on error, e.g. when memory cannot be allocated.

Parameters:

  • set – [out] Set.

  • retain – If true, elements are retained.

Returns:

Initialized iterator.

CowlIterator cowl_iterator_count(ulib_uint *count)

Initializes an iterator that counts the objects it iterates on.

Parameters:

  • count – [out] Object count.

Returns:

Initialized iterator.

CowlIterator cowl_iterator_contains(CowlAny *object)

Initializes an iterator that checks if any of the objects it iterates on is equal to the specified object.

Note

When using this iterator, iterator functions return false if the element has been found.

Parameters:

  • object – The object to look for.

Returns:

Initialized iterator.

Editing ontologies

Ontologies can be edited by adding or removing axioms, annotations and other constructs, as allowed by the CowlOntology API. They can also be created from scratch by calling cowl_manager_get_ontology() and specifying a unique CowlOntologyId or a NULL one, in which case an anonymous ontology is created.

Access to syntactical details that are not relevant to logic, such as the mapping between prefixed and full IRIs, is provided by a CowlSymTable instance retrievable by calling cowl_ontology_get_sym_table().

struct CowlSymTable

Maps symbols to OWL constructs.

Pseudo-extends: CowlObject

CowlTable *cowl_sym_table_get_prefix_ns_map(CowlSymTable *st, bool reverse)

Gets the map that associates prefixes to namespaces.

Parameters:

  • st – The symbol table.

  • reverse – If true, the reversed map (namespaces to prefixes) is returned.

Returns:

Prefix to namespace map, or NULL on error.

CowlString *cowl_sym_table_get_ns(CowlSymTable *st, CowlString *prefix)

Returns the namespace associated with the specified prefix.

Parameters:

  • st – The symbol table.

  • prefix – The prefix.

Returns:

Namespace associated with the prefix, or NULL if the prefix cannot be found.

CowlString *cowl_sym_table_get_prefix(CowlSymTable *st, CowlString *ns)

Returns the prefix associated with the specified namespace.

Parameters:

  • st – The symbol table.

  • ns – The namespace.

Returns:

Prefix associated with the namespace, or NULL if the prefix cannot be found.

cowl_ret cowl_sym_table_register_prefix(CowlSymTable *st, CowlString *prefix, CowlString *ns, bool overwrite)

Registers the specified prefix-namespace mapping.

Parameters:

  • st – The symbol table.

  • prefix – The prefix.

  • ns – The namespace.

  • overwrite – If true, the new mapping overwrites the previous one.

Returns:

Return code.

cowl_ret cowl_sym_table_register_prefix_raw(CowlSymTable *st, UString prefix, UString ns, bool overwrite)

Registers the specified prefix-namespace mapping.

Parameters:

  • st – The symbol table.

  • prefix – The prefix.

  • ns – The namespace.

  • overwrite – If true, the new mapping overwrites the previous one.

Returns:

Return code.

cowl_ret cowl_sym_table_unregister_prefix(CowlSymTable *st, CowlString *prefix)

Unregisters the specified prefix.

Parameters:

  • st – The symbol table.

  • prefix – The prefix.

Returns:

Return code.

cowl_ret cowl_sym_table_unregister_ns(CowlSymTable *st, CowlString *ns)

Unregisters the specified namespace.

Parameters:

  • st – The symbol table.

  • ns – The namespace.

Returns:

Return code.

cowl_ret cowl_sym_table_merge(CowlSymTable *dst, CowlSymTable *src, bool overwrite)

Merges the contents of a symbol table in the current one.

Parameters:

  • dst – The destination symbol table.

  • src – The source symbol table.

  • overwrite – If true, conflicting prefixes are overwritten in the destination.

Returns:

Return code.

CowlIRI *cowl_sym_table_get_full_iri(CowlSymTable *st, UString ns, UString rem)

Retrieves the full IRI associated with the specified short IRI.

Note

You must release the returned object via cowl_release().

Parameters:

  • st – The symbol table.

  • ns – The short namespace.

  • rem – The remainder.

Returns:

IRI instance, or NULL on error.

CowlIRI *cowl_sym_table_parse_full_iri(CowlSymTable *st, UString short_iri)

Retrieves the full IRI associated with the specified short IRI.

Note

You must release the returned object via cowl_release().

Parameters:

  • st – The symbol table.

  • short_iri – The short IRI.

Returns:

IRI instance, or NULL on error.