Archive 2.x:Ontology Read/2

The Ontology Read service is used to query OWL ontologies. All kinds of information can be read on different ontology entities such as: classes, object properties, datatype properties, annotation properties and individuals. Reasoners can also be used to include inferred facts in the service's resultset. A full list of actions can be performed that enables you to leverage your ontologies, properly and effectively.

This service is a Web service wrapper over the OWLAPI ontology library. Most of the API has been implemented. So we can say that this Web service (with the other related OSF Web Service services) turns the OWLAPI into a Web service API.

Developers communicate with the Ontology Read Web service using the HTTP POST method. You may request one of the following mime types: (1) text/xml, (2) application/rdf+xml, (3) application/rdf+n3 or (4) application/json. The content returned by the Web service is serialized using the mime type requested and the data returned depends on the parameters selected.

Version
This documentation page is used for the version 2 of this endpoint. Check at the top of this page to see the documentation pages for the other versions of this endpoint.

Usage
This Web service is intended to be used by content management systems, developers or administrators to manage and access ontologies that are hosted on a OSF Web Service instance, and that are used to describe the concepts and named entities in the system.

If all ontologies in your installation have been given read permissions, then any person or system may be able to query the Ontology Read Web service endpoint to get the complete description of those ontologies. Similarly, you may restrict access to specific ontologies in your installation.

This endpoint, along with the other related endpoints: Ontology Create, Ontology Update and Ontology Delete; can be seen as the "brains" of your OSF Web Service instance.

Web Service Endpoint Information
This section describes all the permissions you need in the WSF (Web Service Framework) to send a query to this Web service endpoint, and it describes how to access it.

To access this Web service endpoint you need the proper CRUD (Create, Read, Update and Delete) permissions on a specific graph (dataset) of the WSF. Without the proper permissions on this graph you won't be able to send any queries to the endpoint.

Needed registered CRUD permission:


 * Create: False
 * Read: True
 * Update: False
 * Delete: False

As shown on the graph URI:


 * URIs of the datasets to be queried

''Note: normally, the URI of an Ontology dataset is the URL used to import that ontology in the system. The URL can be the URI of the ontology if it was resolvable on the Web, or the URL where the OWL file, containing the ontology's description, can be resolved by the server (on the web, on the file system, etc) via a URL.''

Here is the information needed to communicate with this Web service's endpoint. Descriptions of the parameters are included below.

Note: if a parameter has a default value, the requester can omit it and the default value will be used. Also, some baseline Web services may not offer other values than the default.

HTTP method:


 * POST

Possible "Accept:" HTTP header field value:


 * text/xml (structXML)
 * application/json (structJSON)
 * application/rdf+xml (RDF+XML)
 * application/rdf+n3 (N3/Turtle)
 * application/iron+json (irJSON)
 * application/iron+csv (commON)

URI:


 * http://[...]/ws/ontology/read/ ?ontology=param1&function=param2&parameters=param3&reasoner=param4&registered_ip=param5&interface=param6&lang=param7

URI dynamic parameters description:

Note: All parameters have to be URL-encoded


 * param1. URI of the ontology; the URI of an Ontology dataset is the URL used to import that ontology in the system. The URL can be the URI of the ontology if it was resolvable on the Web, or the URL where the OWL file, containing the ontology's description, can be resolved by the server (on the web, on the file system, etc) via a URL. If you don't know what the URI is, you can always use the  function to get the list of all loaded ontologies URI.
 * param2. The function name to use for this query. The complete list of function names and their descriptions is available below.
 * param3. The list of parameters used by the function you are about to use. The parameters are split by a ";" character. The parameter and its value are defined as . This tuple has to be encoded. So, the parameters should be constructed that way in the URL:  . See the example below.
 * param4. On of:
 * True (Default) &mdash; Enable the reasoner for this query
 * False &mdash; Disable the reasoner for this query
 * param5. Target IP address registered in the WSF. Needed when param1 = "access_user". Otherwise this parameter as to be omitted.
 * param6. Source interface used for this web service query. The interface is a different way to process a query (different algorithms, different data management system, etc. The default interface is 'default'
 * param7. (default: en) Language of the records to be returned by the search endpoint. Only the textual information of the requested language will be returned to the user. If no textual information is available for a record, for a requested language, then only non-textual information will be returned about the record.The default is "en"; however, if the parameter is an empty string, then all the language strings for the record(s) will be returned.

Available Sources Interfaces
A source interface is a way to process a web service query. Different sources interfaces can be implemented for the same OSF Web Service endpoint. Each interface will process the query differently, but all the queries to the web service endpoint will be the same, at the exception of the  parameter. Each interface shares the same API (the one defined by the web service endpoint), but their processing may differ (like using different algorithms, using different data management systems, etc.)

This is a list of the core interfaces for this endpoint. Organizations that hosts a OSF Web Service network could create their own interface and make it available to the users. However such private source interface won't be part of this list, but should be publicized by the organization.

Functions
The Ontology Read Web service endpoint supports a series of functions that can be queried. All of the functions are listed in the section below, along with all their parameters.

All queries are built the same way:


 * http://[...]/ws/ontology/read/ parameters: ontology=http%3A%2F%2Fsome-ontology-uri&function=getClasses&parameters=mode%3Duris%3Blimit%3D10%3Boffset%3D0

Where:


 * ontology is the URI of the ontology to query
 * function is the name of the function to use for that query
 * parameters is a list of encoded parameters/values to give as input to that function

Classes Related Functions
All functions related to classes of an ontology.

getClass
Get the description of a class, in a target ontology.

getClasses
Get all the classes that have been defined in an ontology. The requester can get a list of URIs or the full description of the classes.

getDatatypes
Get all the datatypes that have been defined in an ontology. The requester can get a list of URIs or the full description of the datatypes.

getSubClasses
Get all the sub-classes of a target class of the ontology. The requester can get a list of URIs or the full description of the sub-classes.

getSuperClasses
Get all the super-classes of a target class of the ontology. The requester can get a list of URIs or the full description of the super-classes.

getEquivalentClasses
Get all the equivalent-classes of a target class of the ontology. The requester can get a list of URIs or the full description of the equivalent-classes.

getDisjointClasses
Get all the disjoint-classes of a target class of the ontology. The requester can get a list of URIs or the full description of the disjoint-classes.

Properties Related Functions
All functions related to properties of an ontology.

getProperty
Get the description of a property, in a target ontology.

getProperties
Get all the properties that have been defined in an ontology. The requester can get a list of URIs or the full description of the properties.

getSubProperties
Get all the sub-properties that have been defined in an ontology. The requester can get a list of URIs or the full description of the sub-properties.

getSuperProperties
Get all the super-properties that have been defined in an ontology. The requester can get a list of URIs or the full description of the super-properties.

getDisjointProperties
Get all the disjoint-properties that have been defined in an ontology. The requester can get a list of URIs or the full description of the disjoint-properties.

getEquivalentProperties
Get all the equivalent-properties that have been defined in an ontology. The requester can get a list of URIs or the full description of the equivalent-properties.

Named Individuals Related Functions
All functions related to named individuals of an ontology.

getNamedIndividual
Get the description of a named individual, in a target ontology.

getNamedIndividuals
Get all the named individuals that belongs to a class that have been defined in an ontology. The requester can get a list of URIs or the full description of the named individuals.

Other Functions
Functions related to other aspects of reading an ontology.

getLoadedOntologies
Get the list of all loaded ontologies on that OSF Web Service node.

getOntologies
Get the list of all the ontologies of the import closure of the ontology being queried. If you want to get the list of all individually loaded ontologies file of this instance, use the getLoadedOntologies API call instead.

getSerialized
Get the serialized document that represents the OWL ontology. The serialization format (usually RDF+XML or RDF+N3) depends on the format used when the ontology got created. The same format will be used as an output of this function call.

There are no function parameters for this function call. The ontology to serialize is determined by the  query parameter.

getSerializedClassHierarchy
Get the serialized PHP array structure, used by OSF-Drupal and OSF Web Service, that represents the classes structure of the OWL ontology.

There are no function parameters for this function call. The ontology to serialize is determined by the  query parameter.

getSerializedPropertyHierarchy
Get the serialized PHP array structure, used by OSF-Drupal and OSF Web Service, that represents the properties structure of the OWL ontology.

There are no function parameters for this function call. The ontology to serialize is determined by the  query parameter.

getIronXMLSchema
Get the ironXML Schema, used by the Semantic Components, that represents the OWL ontology.

There are no function parameters for this function call. The ontology to serialize is determined by the  query parameter.

getIronJsonSchema
Get the ironJSON Schema, used by the Semantic Components, that represents the OWL ontology.

There are no function parameters for this function call. The ontology to serialize is determined by the  query parameter.

Example of Returned XML Document
This is an example of the XML document returned by this Web service endpoint for a given URI. This example returns a list of datasets accessible by a given user IP.

Query:


 * http://[...]/ws/ontology/read/ parameters: function=getClass&ontology=file%3A%2F%2Flocalhost%2Fdata%2Fontologies%2Ffiles%2Ftest-1.0.owl&parameters=uri%3Dfile%3A%2F%2Flocalhost%2Fdata%2Fontologies%2Ffiles%2Ftest

"Accept:" HTTP header field value:


 * text/xml

Result:

HTTP Status Codes
Here are the possible HTTP status (error) codes returned by this Web service endpoint.

On error code and the specific error, a different message description can be issued (meaning a different error has been returned).


 * Code:200
 * Message: OK


 * Code:400
 * Message: Bad Request
 * Message description: The function call being requested is unknown or unsupported by this Ontology Read web service endpoint.
 * Message description: Unsupported mode used for this query.
 * Message description: You omitted to provide the URI parameter for this query.
 * Message description: Unsupported type used for this query
 * Message description: The target ontology is not loaded into the ontological structure of this instance.
 * Message description: No requester IP available
 * Message description: No Web service URI available
 * Message description: Target Web service XYZ not registered to this Web Services Framework
 * Message description: No access defined for this requester IP XYZ, dataset (XYZ) and Web service (XYZ)
 * Message description: The target Web service (XYZ) needs read access and the requested user (XYZ) doesn't have this access for that dataset (XYZ)


 * Code:406
 * Message: Not Acceptable
 * Message description: Unacceptable mime type requested


 * Code:500
 * Message:Internal Error