SSWAP HTTP API


NAME

/makeType — make a Type (an OWL class)

SYNOPSIS

e.g., curl -d @<jsonFile> http://sswap.info/api/makeType[?prefix1=... [&prefix2=...]]

DESCRIPTION

/makeType is the basename of a URL for a RESTful web service that converts JSON (Javascript Object Notation) into an OWL RDF/XML class (owl:Class) for use in semantic web services. Input is sent to the URL via a HTTP POST, for example by a program such as curl or wget. A HTTP GET on /makeType (for example, as initiated by visiting the URL with a browser) returns this manual page. Content negotiation may be used to return a machine parsable JSON schema if the requested response MIME type is application/json.

A typical motif in OWL is to serialize multiple ontology terms into a single file, differentiating individual terms by the use of the fragment identifier ('#'): e.g., http://www.w3.org/2002/07/owl#Class. This is acceptable for the standard namespaces (such as owl) because the semantics of the terms are pre-defined and do not require dereferencing at transaction time. The fragment identifier ('#') is a user-agent identifier (RFC 3986), and is used solely by clients after document retrieval for relative referencing. Strict server-side adherence means that servers should satisfy a URL request without bias to the fragment identifier, leaving relative referencing to the client.

This creates a challenge for semantic web services because ontologies with hundreds-of-thousands to millions of terms, all referenced by the same URI with only fragment identifier differentiation, yield no clean model on how to retrieve relevant OWL statements for only a few terms.  Even for ontologies of only a few hundred terms, a requirement to serialize and transmit an entire ontology when only a few terms are needed creates an unworkable environment for the dozens of ontologies that may be used in RDGs, RIGs, RRGs, and RQGs. Dereferencing terms to retrieve their OWL statements is required in a distributed semantic web services model because terms exist in a dynamic environment where there is no fixed, a priori semantic for user-defined terms. A simple solution is to differentiate terms with a slash ('/') instead of a hash ('#'), essentially authorizing the server to make each term individually dereferenceable as an atomic web resource. Complete ontologies can then be reconstructed by various mechanisms; examples are at http://sswapmeet.sswap.info.

/makeType creates an RDF/XML owl:Class from a simplified JSON input specification.

/makeType is hosted as a public service at http://sswap.info/api/makeType.

Quick Start

Here, we use the program curl to POST the in-line JSON content to the public /makeType service:

curl -d '

{

    "prefix" : { "taxa" : "http://sswapmeet.sswap.info/Taxa/" },


    "taxa:Taxa" : {

        "rdfs:label" : "Taxa",

        "rdfs:comment" : "A high level wrapper class for taxonomic data."

    }

}

' http://sswap.info/api/makeType

(For Windows CMD.exe users, see USAGE NOTES below). The response from /makeType is an OWL RDF/XML document suitable for semantic web services. By convention, types (OWL classes) start with a capital letter (e.g., Taxa). The rdfs prefix, as well as the prefixes sswap, rdf, xsd, and owl are always available and do not need to be defined explicitly. The resultant document should be hosted on the web at the <ResourceURI> (taxa:Taxa).

JSON Format

Input follows standard JSON syntax with built-in support for generating SSWAP documents as described in the JSON Syntax (see also SSWAP HTTP API).

EXAMPLES

The command:

curl http://sswap.info/api/makeType

executes an HTTP GET and retrieves this manual page. Because this is a simple GET, you can accomplish the same action by simply visiting the link with your browser. Alternatively, to have a machine-readable schema returned instead of HTML, use content negotiation to request the JSON schema:

curl -H 'Accept: application/json' http://sswap.info/api/makeType

To generate an owl:Class from JSON, the command:

curl -d @myJSONInputFile http://sswap.info/api/makeType

will POST the contents of myJSONInputFile to the public service.  The response is an OWL RDF/XML class. Optionally, you can inform the service of the MIME type of the content you are sending by adding the header option -H 'Content-Type: application/json'.  The service is guaranteed to accept this MIME type, so for generating content programmatically, this header option guarantees that the input will be accepted.

On many operating systems you can also in-line content such as in the Quick Start example above and the example below:

curl -d '

{

    "api" :  "/makeType",


    "prefix" : {

        "grqtl" : "http://sswap.gramene.org/vpin/ontologies/qtl/",

        "map"   : "http://sswapmeet.sswap.info/map/"

     },


    "grqtl:QtlByLinkageGroupRequest" : {


        "rdfs:label" : "Qtl by linkage group",


        "rdfs:comment" : "The QtlByLinkageGroupRequest class represents information that must be provided in a qtl-by-linkage-group resource graph by a client in order to retrieve a Qtl object (see the resource description graph at http://sswap.gramene.org/vpin/qtl-by-linkage-group for details). The data to be provided consists of a linkage group (represented by the map:linkageGroup property)",


        "map:linkageGroup" : { "owl:cardinality" : 1 }

    }

}

' http://sswap.info/api


The contents between and including the opening and closing curly braces { } are exemplary of the contents of myJSONInputFile. When in-lining content, note the use of opening and closing single quotes (') around the braces { }; this protects the contents from interpretation by the shell in many operating systems. The "map:linkageGroup" : { "owl:cardinality" : 1 } construct establishes an owl:Restriction on the property map:linkageGroup as part of the class' definition.  See JSON Syntax Summary for details.  SSWAP uses a highly distributed model of data re-use. /makeType deferences URLs as part of determining constraints and constructing the graph.

USAGE NOTES

The Windows CMD.exe command shell does not recognize in-line quoted strings as in the examples above; in that case, save the contents into a file and use the -d @myJSONInputFile syntax.


/makeType is a convenience service to enable a non-semantic JSON specification to generate a semantic OWL RDF/XML owl:Class. Using it guarantees that the resultant owl:Class is OWL DL and SSWAP compliant, while allowing the specification to be in JSON instead of the more obtuse OWL RDF/XML. Users who want to construct and deploy many classes (and properties; see /makeProperty) from a single ontology may choose to use an ontology editor such as Protege and the OWL File Splitting service available at http://sswap.info. Developers are encouraged to use the SSWAP Java API for finer-grained control than is available with the HTTP API.

DIAGNOSTICS

If /makeType returns content (RDF/XML), it is guaranteed to be a valid SSWAP-compliant OWL DL owl:Class. In these cases the HTTP response code is always '200 OK'. If /makeType cannot return content (for example, because of an unrecoverable parsing error on the JSON input), it will return a HTTP error code other than '200 OK'.


Note: curl may return an exit code of 0 (success) even if the HTTP response code is not 200. See curl for details and ways to change this behavior.

STANDARDS

Input format is standard JSON, with recognition for the reserved strings "prefix" and "imports". Output format is OWL 2 (DL) RDF/XML.

SEE ALSO

SSWAP Home: sswap.info

SSWAP Wiki: sswap.info/wiki

SSWAP Just-In-Time Ontology Editor: sswap.info/jit

SSWAP Java API: sswap.info/javadocs

SSWAP SDK (Software Development Kit): sswap.info/sdk

JSON: http://json.org

JSON validators: http://www.jslint.com, http://www.jsonlint.com

OWL: http://www.w3.org/TR/owl2-overivew

RDF/XML: http://www.w3.org/TR/REC-rdf-syntax

AUTHORS

Damian Gessler, Blazej Bulka

AVAILABILITY

The software is open source.

/makeType

/makeType

/makeProperty