Best Practice Site Layout

• A Provider file (e.g., resourceProvider) which is a machine-readable (and to an extent human-readable) SSWAP OWL DL RDF/XML file with a single sswap:Provider instance that enumerates the semantic web service instances of sswap:Resource that this site provides. Usually a site has only one Provider, providing one or more Resources, though there is nothing architecturally that would prohibit a site from hosting multiple Providers. See the SSWAP Protocol for Provider and Resource.
• A resources directory that contains a subdirectory for each resource. Each resource directory (e.g., sswap.info/examples/resources/canonical) will normally contain the following items:
  • A Resource file (e.g., canonicalResource) which is a machine-readable (and to an extent human-readable) SSWAP OWL DL RDF/XML file with a single sswap:Resource instance. This file is called the Resource Description Graph (RDG) for the resource and is the actual semantic web service you are offering. The URL of the file must match the URL of the sswap:Resource defined in the file (e.g., sswap.info/examples/resources/canonical/canonicalResource). Executing a simple HTTP GET on this address returns the file; thus anyone can see your definition of your semantic web service by simply GETting the file. Use this to your advantage; for example, search on any term at sswap.info and click on the RDF icon next to the resource name on the results page to see how that resource defines itself. Use these as well as the examples here as templates to help you write your own RDGs. Note how the RDG structure implements the SSWAP Protocol. Once your RDG is written, validate it with the SSWAP validator. To let sswap.info know about your service, publish it. Publishing automatically calls the validator. Publishing per se does nothing to activate your service, but it does allow us to discover it and add it to the knowledge base supplying the discovery at sswap.info. To "unpublish" your service with us, simply remove or otherwise invalidate the RDG and publish the URL again. When we investigate a URL for unpublishing, we'll detect that it is no longer a valid SSWAP resource and will remove it from our knowledge base. It may take some time before our engines rebuild the knowledge base and remove your service. To activate your service, you need to set up your web server to respond to HTTP POSTs and GETs. We have a Software Development Kit to help you with this; please see our Developer's Page and contact us.
    
    In summary, hosting a SSWAP semantic web service means supporting as few as two URLs on your web server: one to define you or your institution as the Provider of the resource and one as the actual semantic web service Resource itself. These URLs must be distinct. "Supporting a URL" means, in the case of the Provider URL, your web server returns the SSWAP OWL DL RDF/XML file defining the Provider on a HTTP GET; in the case of the Resource URL, it means returning the SSWAP OWL DL RDF/XML file defining the service on an HTTP GET and invoking (executing) the service on a HTTP POST. It is up to you if the files physically and statically exist on your server or if your web server interprets the URL and dynamically generates content. It is common for sites to have one Provider and multiple Resources (services). Other files can be helpful to your users are called out by the Protocol and are outlined below:
  • [Optional] An HTML file (or other browser-displayable URL such as a JSP) containing additional information and links about the resource for your users. The URL of this file is the literal value of the sswap:aboutURI property.
  • [Optional] An HTML file (or other browser-displayable URL such as a JSP) containing a web front-end for users to invoke the service. This is a way to make semantic web services not only accessible to machines, but also associated with an input presentation layer invokable by your users. The URL of this file is the literal value of the sswap:inputURI property.
  • [Optional] An HTML file (or other browser-displayable URL such as a JSP) containing a web front-end for users to view formatted results of the service. This is a way to make semantic web services not only accessible to machines, but also associated with an output presentation layer displayable for your users. The URL of this file is the literal value of the sswap:outputURI property.
  • [Optional] A plain text file containing words and phrases that you want semantic search engines to associate with your service. This file is an aid to third-parties for making lexical matches to your service (for example, by associating species or gene names with your service). You have complete control of the content, but you do not have control over how it is used by third-parties. This file is solely as a helper file for third-party lexical associations; to semantically tag the input and/or output data of your service, use OWL DL and ontological classes and predicates (for example as found at sswapmeet.sswap.info) to annotate the SSWAP graphs themselves. The URL of this file is the literal value of the the sswap:metadata property.
• [Optional] An ontologies directory that contains OWL ontology term definitions. An important architectural property of SSWAP is its support for a shared semantic; in other words, people using, sharing, and extending ontological terms under the formal semantics of SSWAP and OWL. A portal for ontologies is hosted at sswapmeet.sswap.info. If these terms defined by others are sufficient for your needs, you do not need to define your own ontological terms – simply reference those of others and define your service and its data types. If the ontological terms of others do not suit you needs, you can define and extend your own. Ontological terms must be OWL DL serialized in RDF/XML, each term in its own file. In this manner, anyone can execute a HTTP GET on any term and get its atomic definition; follow the URLs and semantics of other terms used in the definition to get the term's extended logical implications. A best practice is to create subdirectories to hold all the terms for a given ontology. For example, the example speciesInformationPage resource on the SSWAP web site uses terms from the MySpeciesRecord ontology. Many more examples are at sswapmeet.sswap.info. Such ontologies can be created by the Protégé ontology editor and split into constituent term files using the SSWAP OWL Ontology Splitter. The Ontology Splitter page provides some ontology authoring guidelines, and enumerates the files produced by the splitting process. These split files are what should be in the ontology subdirectory. Your ontologies are available to anyone by virtue of your web server; if you would like us to host a link to your work at sswapmeet.sswap.info to heighten their exposure, email us and we will be happy to do so.
• [Optional] A README file (such as what you are reading now) that provides a human readable index of the SSWAP resources and ontology terms that are provided. The file could be plain text or HTML, or if the site supports Java Servlet Pages, it can contain a mixture of HTML and JSP code as does this site.

Example Resources on sswap.info