Ontology Read

From OSF Wiki
Jump to: navigation, search
Ontology: Read endpoint version:
1.1
2
3

The Ontology Read service is used to query OWL ontologies. All kinds of information can be read from the specified ontology 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 Web service is a wrapper over the OWLAPI ontology library. Most of the API has been implemented. Essentially, this service (along with its other related 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 3 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=&function=&parameters=&reasoner=&interface=&lang=&version=

URI dynamic parameters description:

Note: All parameters have to be URL-encoded

  • ontology. 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 getLoadedOntologies function to get the list of all loaded ontologies URI.
  • function. The function name to use for this query. The complete list of function names and their descriptions is available below.
  • parameters. 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 param-1=value-1. This tuple has to be encoded. So, the parameters should be constructed that way in the URL: &parameters=urlencode("param-1=value-1");urlencode("param-2=value-2"). See the example below.
  • reasoner. On of:
    • True (Default) — Enable the reasoner for this query
    • False — Disable the reasoner for this query
  • interface. 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'
  • lang. (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.
  • version. (default: 3.0) Version of the interface to query

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 interface 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.


Source Interface Name Description
default Default source interface for this OSF Web Service endpoint. This interface implements the default behavior of this OSF Web Service endpoint.

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.

Function Parameters Parameter optional? Values Description
uri No Any URI string The URI of the class for which you want its description

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.

Function Parameters Parameter optional? Values Description
mode No "uris" Get a list of URIs that refers to the classes described in this ontology.
"descriptions" Get the list of classes description for the classes described in this ontology
limit Yes Integer The number of results the requester wants in the resultset.
offset Yes Integer Where the results to return starts in the complete list of results. This is normally used in conjunction with the limit parameter to paginate the complete list of 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.

Function Parameters Parameter optional? Values Description
mode No "uris" Get a list of URIs that refers to the datatypes described in this ontology.
"descriptions" Get the list of datatypes description for the datatypes described in this ontology
limit Yes Integer The number of results the requester wants in the resultset.
offset Yes Integer Where the results to return starts in the complete list of results. This is normally used in conjunction with the limit parameter to paginate the complete list of classes.

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.

Function Parameters Parameter optional? Values Description
uri No URI string URI of the class for which the requester want its sub-classes.
mode No "uris" Get a list of URIs that refers to the sub-classes described in this ontology.
"descriptions" Get the list of classes description for the sub-classes described in this ontology
"hierarchy" Get the list of classes description for the sub-classes described in this ontology. The class description being returned is a lightweight version of the full "descriptions" mode. The goal is to manipulate and transmit a simpler structure such as what might be used by a user interface to display some parts of the hierarchy of an ontology. What is returned is all the annotation properties (used to get some label to display for one of the sub-class) and a possible attribute: "sco:hasSubClass" which has "true" as value. If this triple exists, it means that the sub-class has itself other subclasses (this is mainly used to be able to display an "extend" button in a tree control).
direct Yes False (default) Get all the sub-classes by inference (so, the sub-classes of the sub-classes recursively).
True Only get the direct sub-classes of the target class.

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.

Function Parameters Parameter optional? Values Description
uri No URI string URI of the class for which the requester want its super-classes.
mode No "uris" Get a list of URIs that refers to the super-classes described in this ontology.
"descriptions" Get the list of classes description for the super-classes described in this ontology
direct Yes False (default) Get all the super-classes by inference (so, the sub-classes of the super-classes recursively).
True Only get the direct super-classes of the target class.

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.

Function Parameters Parameter optional? Values Description
uri No URI string URI of the class for which the requester want its equivalent-classes.
mode No "uris" Get a list of URIs that refers to the equivalent-classes described in this ontology.
"descriptions" Get the list of classes description for the equivalent-classes described in this ontology

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.

Function Parameters Parameter optional? Values Description
uri No URI string URI of the class for which the requester want its disjoint-classes.
mode No "uris" Get a list of URIs that refers to the disjoint-classes described in this ontology.
"descriptions" Get the list of classes description for the disjoint-classes described in this ontology

Properties Related Functions

All functions related to properties of an ontology.

getProperty

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

Function Parameters Parameter optional? Values Description
uri No Any URI string The URI of the property for which you want its description

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.

Function Parameters Parameter optional? Values Description
type No "dataproperty" Get all the Datatype properties of the ontology
"objectproperty" Get all the Object properties of the ontology
"annotationproperty" Get all the Annotation properties of the ontology
"all" (default) Get all the Datatype, Object and Annotation properties of the ontology
mode No "uris" Get a list of URIs that refers to the classes described in this ontology.
"descriptions" Get the list of properties description for the properties described in this ontology
limit Yes Integer The number of results the requester wants in the resultset.
offset Yes Integer Where the results to return starts in the complete list of results. This is normally used in conjunction with the limit parameter to paginate the complete list of classes.

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.

Function Parameters Parameter optional? Values Description
uri No URI string URI of the property for which the requester want its sub-properties.
type No "dataproperty" Get all the Datatype sub-properties of the ontology
"objectproperty" Get all the Object sub-properties of the ontology
mode No "uris" Get a list of URIs that refers to the sub-properties described in this ontology.
"descriptions" Get the list of sub-properties description for the sub-properties described in this ontology
direct Yes False (default) Get all the sub-properties by inference (so, the sub-properties of the sub-properties recursively).
True Only get the direct sub-properties of the target class.

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.

Function Parameters Parameter optional? Values Description
uri No URI string URI of the property for which the requester want its super-properties.
type No "dataproperty" Get all the Datatype super-properties of the ontology
"objectproperty" Get all the Object super-properties of the ontology
mode No "uris" Get a list of URIs that refers to the super-properties described in this ontology.
"descriptions" Get the list of super-properties description for the super-properties described in this ontology
direct Yes False (default) Get all the super-properties by inference (so, the super-properties of the super-properties recursively).
True Only get the direct super-properties of the target class.

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.

Function Parameters Parameter optional? Values Description
uri No URI string URI of the property for which the requester want its disjoint-properties.
type No "dataproperty" Get all the Datatype disjoint-properties of the ontology
"objectproperty" Get all the Object disjoint-properties of the ontology
mode No "uris" Get a list of URIs that refers to the disjoint-properties described in this ontology.
"descriptions" Get the list of disjoint-properties description for the disjoint-properties described in this ontology

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.

Function Parameters Parameter optional? Values Description
uri No URI string URI of the property for which the requester want its equivalent-properties.
type No "dataproperty" Get all the Datatype equivalent-properties of the ontology
"objectproperty" Get all the Object equivalent-properties of the ontology
mode No "uris" Get a list of URIs that refers to the equivalent-properties described in this ontology.
"descriptions" Get the list of equivalent-properties description for the equivalent-properties described in this ontology

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.

Function Parameters Parameter optional? Values Description
uri No Any URI string The URI of the named individual for which you want its description

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.

Function Parameters Parameter optional? Values Description
classuri No Any URI string of any class Get all the named individuals belonging to that class URI
mode No "uris" Get a list of URIs that refers to the named individuals described in this ontology.
"descriptions" Get the list of named individuals description described in this ontology
"list" Get the list of named individuals description described in this ontology. This list of named individuals has been optimized for list controls. Only the types and the prefLabel of the named individual has been added to its description.
direct Yes False (default) Get all the named individuals that belong directly to that class referenced by the classuri parameter.
True Get all the named individuals that belong to the class referenced by the classuri parameter, and all the named individuals that belongs to all the super-classes of that target class.
limit Yes Integer The number of results the requester wants in the resultset.
offset Yes Integer Where the results to return starts in the complete list of results. This is normally used in conjunction with the limit parameter to paginate the complete list of classes.

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.

Function Parameters Parameter optional? Values Description
mode No "uris" Get the list of URIs of all the loaded ontologies. These URIs are used as a value of the ontology parameter for the other function calls.
"descriptions" Get the list of all the URIs of all the loaded ontologies and their description (title, description, etc). These URIs are used as a value of the ontology parameter for the other function calls.

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.

Function Parameters Parameter optional? Values Description
mode No "uris" Get the list of URIs of all the imported ontologies in the queried ontology.

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

  1. <?xml version="1.0" encoding="utf-8"?>
  2. <!DOCTYPE resultset PUBLIC "-//Structured Dynamics LLC//Ontology Read DTD 0.1//EN" "ontology/ontologyRead.dtd">
  3. <resultset>
  4.   <prefix entity="owl" uri="http://www.w3.org/2002/07/owl#"/>
  5.   <prefix entity="rdf" uri="http://www.w3.org/1999/02/22-rdf-syntax-ns#"/>
  6.   <prefix entity="rdfs" uri="http://www.w3.org/2000/01/rdf-schema#"/>
  7.   <prefix entity="wsf" uri="http://purl.org/ontology/wsf#"/>
  8.   <prefix entity="aggr" uri="http://purl.org/ontology/aggregate#"/>
  9.   <subject type="owl:Class" uri="file://localhost/data/ontologies/files/test">
  10.     <predicate type="rdfs:label">
  11.       <object type="rdfs:Literal">Test</object>
  12.     </predicate>
  13.     <predicate type="rdfs:comment">
  14.       <object type="rdfs:Literal">Here is a test class with some description.</object>
  15.     </predicate>
  16.     <predicate type="rdfs:subClassOf">
  17.       <object uri="http://www.w3.org/2002/07/owl#Thing">
  18.         <reify type="rdfs:Label" value=" Thing"/>
  19.       </object>
  20.     </predicate>
  21.   </subject>
  22. </resultset>


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).


HTTP 200

Message Description
OK


HTTP 400

ID Level Name Description
WS-ONTOLOGY-READ-200 Warning Unknown function call The function call being requested is unknown or unsupported by this Ontology Read web service endpoint
WS-ONTOLOGY-READ-201 Warning Unsupported mode Unsupported mode used for this query
WS-ONTOLOGY-READ-202 Warning URI parameter not provided You omited to provide the URI parameter for this query.
WS-ONTOLOGY-READ-203 Warning Unsupported type Unsupported type used for this query
WS-ONTOLOGY-READ-204 Warning Property not existing The target property URI is not existing in the target ontology.
WS-ONTOLOGY-READ-205 Warning Class not existing The target class URI is not existing in the target ontology.
WS-ONTOLOGY-READ-206 Warning Named individual not existing The target named individual URI is not existing in the target ontology.
WS-ONTOLOGY-READ-300 Warning Target ontology not loaded The target ontology is not loaded into the ontological structure of this instance.
WS-ONTOLOGY-READ-301 Fatal Requested source interface not existing The source interface you requested is not existing for this web service endpoint.
WS-ONTOLOGY-READ-302 Fatal Requested incompatible Source Interface version The version of the source interface you requested is not compatible with the version of the source interface currently hosted on the system. Please make sure that your tool get upgraded for using this current version of the endpoint.
WS-ONTOLOGY-READ-303 Fatal Source Interface's version not compatible with the web service endpoint's The version of the source interface you requested is not compatible with the one of the web service endpoint. Please contact the system administrator such that he updates the source interface to make it compatible with the new endpoint version.
WS-ONTOLOGY-READ-304 Fatal Language not supported by the endpoint The language you requested for you query is currently not supported by the endpoint. Please use another one and re-send your query.

HTTP 403

ID Level Name Description
WS-AUTH-VALIDATION-100 Fatal Unauthorized Request Your request cannot be authorized for this web service call
WS-AUTH-VALIDATION-101 Fatal Unauthorized Request Your request cannot be authorized for this web service call
WS-AUTH-VALIDATION-102 Fatal Couldn't authorize request An internal error occured when we tried to authorize this request
WS-AUTH-VALIDATION-103 Fatal Unauthorized Request Your request cannot be authorized for this user: "---", on this dataset: "---", using this web service endpoint: "---"


HTTP 406

Message Description
Not Acceptable Unacceptable mime type requested


HTTP 500

Message Description
Internal Error