SSWAP HTTP API


NAME

/makeProperty — make a Property (an OWL ObjectProperty or OWL DatatypeProperty)

SYNOPSIS

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

DESCRIPTION

/makeProperty is the basename of a URL for a RESTful web service that converts JSON (Javascript Object Notation) into an OWL RDF/XML property (owl:ObjectProperty or owl:DatatypeProperty) 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 /makeProperty (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.

/makeProperty is the analog to /makeType, but for OWL properties (predicates). /makeProperty creates an RDF/XML owl:ObjectProperty or owl:DatatypeProperty from a simplified JSON input specification.

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

Quick Start

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

curl -d '

{

    "prefix" : {

        "ncbiTaxa" : "http://sswapmeet.sswap.info/NCBITaxonomyRecord/"

    },


    "ncbiTaxa:commonName" : {


        "rdfs:subPropertyOf" : "ncbiTaxa:datatypeProperties",


        "rdfs:label" : "Common Name",

        "rdfs:comment" : "A common name for the taxonomic record. Records may have zero, one, or many common names.",


        "rdfs:range"  : "xsd:string",

        "rdfs:domain" : "ncbiTaxa:TaxonomyRecord"


    }

}

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

(For Windows CMD.exe users, see USAGE NOTES below). The response from /makeProperty is an OWL RDF/XML document suitable for semantic web services. By convention, properties (OWL predicates) start with a lower-case letter (e.g., commonName). 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> (ncbiTaxa:commonName).

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/makeProperty

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/makeProperty

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

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

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" :  "/makeProperty",


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


    "map:hasMappableObject" : {


        "rdfs:subPropertyOf" : "map:objectProperties",


        "rdfs:comment" : "Relates a Map or MapPosition to a MappableObject (a mappable element).",


        "rdfs:range"  : "map:MappableObject",

        "rdfs:domain" : {

            "owl:unionOf" : [

                "map:Map",

                "map:MapCorrespondence",

                "map:MapPosition"

            ]

        }

    }

}

' 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 owl:unionOf construct illustrates the one of the many OWL capabilities supported.  See JSON Syntax Summary for details.  SSWAP uses a highly distributed model of data re-use. /makeProperty deferences URLs as part of determining constraints and constructing the graph (e.g., dereferencing map:objectProperties to deduce that map:hasMappableObject must be an owl:ObjectProperty).

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.


/makeProperty is a convenience service to enable a non-semantic JSON specification to generate a semantic OWL RDF/XML owl:ObjectProperty or owl:DatatypeProperty. Using it guarantees that the resultant property 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 properties (and classes; see /makeType) 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 /makeProperty returns content (RDF/XML), it is guaranteed to be a valid SSWAP-compliant OWL DL property. In these cases the HTTP response code is always '200 OK'. If /makeProperty cannot return content (for example, because of an unrecoverable parsing error on the JSON input or a logical inconsistency rendering the property both an owl:ObjectProperty and an owl:DatatypeProperty), 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.

/makeProperty

/makeType

/makeProperty