Schema Introduction
All of the messages between Servers and Clients use a JSON-based schema. A full example of this is shown below and then each part will get described in turn. There are Examples
Any message can have a header, much like the <head> tag in a web page and although this is optional it is recommended that all messages have one of these. The information contained in it are items such as the version of the Grassroots schema and the incoming request.
Where possible existing standardised ontologies and their terms are used, trying to keep the number of Grassroots-specific terms to a minimum. Various ontologies are currently used and these are shown below:
Schema | Prefix | Description |
---|---|---|
schema.org | so | Schema.org is a collaborative, community activity with a mission to create, maintain, and promote schemas for structured data on the Internet. |
EDAM Ontology | eo | EDAM is a comprehensive ontology of well-established, familiar concepts that are prevalent within bioinformatics and computational biology, including types of data and data identifiers, data formats, operations and topics |
Experimental Factor Ontology | efo | The Experimental Factor Ontology (EFO) provides a systematic description of many experimental variables available in EBI databases, and for external projects such as the NHGRI GWAS catalog |
Software Ontology | swo | The Software Ontology (SWO) is a resource for describing software tools, their types, tasks, versions, provenance and data associated. |
Header
Each message can contain a header section that stores the details about various features that are not necessarily related to running services such as the version of the schema that is being used, datestamps, etc. It can currently contain the following elements
- schema: This specifies the details about the Grassroots schema being used and currently contains the following keys:
- major: The major revision of the Grassroots schema being used.
- minor: The major revision of the Grassroots schema being used.
So an example specifying that version 0.10 of the Grassroots schema is being used would be:
Operations
The Operations tag is used to make an API call to a Grassroots Server. It contains a single key-value pair.
- operation (required): A string which equates to a particular API call for the Operation.
Value | C variable | Description |
---|---|---|
get_all_services | OP_LIST_ALL_SERVICES | Get a list of all of the Services that the Server can offer. |
get_schema_version | OP_GET_SCHEMA_VERSION | Get the SchemaVersion that the Server is using. |
get_interested_services | OP_LIST_INTERESTED_SERVICES | Get a list of the Services that are able to run on a given Resource. |
run_keyword_services | OP_RUN_KEYWORD_SERVICES | Run all of the Services that have Keyword Parameters. |
get_named_service | OP_GET_NAMED_SERVICES | Get list of services matching the given names. |
get_service_results | OP_GET_SERVICE_RESULTS | Get results or the status of jobs. |
get_resource | OP_GET_RESOURCE | Get a requested Resource from the Server. |
get_server_status | OP_SERVER_STATUS | Get the status of the Grassroots server. |
So, for example, the JSON-based request to get a list of all available Services would be:
Example
Operations
The Operations tag is used to call an API on the Server.
- operation (required): A string which equates to a particular API call for the Operation.
Value | C variable | Description |
---|---|---|
get_all_services | OP_LIST_ALL_SERVICES | Get a list of all of the Services that the Server can offer. |
get_schema_version | OP_GET_SCHEMA_VERSION | Get the SchemaVersion that the Server is using. |
get_interested_services | OP_LIST_INTERESTED_SERVICES | Get a list of the Services that are able to run on a given Resource. |
run_keyword_services | OP_RUN_KEYWORD_SERVICES | Run all of the Services that have Keyword Parameters. |
get_named_service | OP_GET_NAMED_SERVICES | Get list of services matching the given names. |
get_service_results | OP_GET_SERVICE_RESULTS | Get results or the status of jobs. |
get_resource | OP_GET_RESOURCE | Get a requested Resource from the Server. |
get_server_status | OP_SERVER_STATUS | Get the status of the Grassroots server. |
So, for example, the JSON-based request to get a list of all available Services is:
Service
- so:name (required): The user-friendly name of the Service which will be displayed to the user.
- so:url: A web address for more information about the Service.
- so:description (required): A user-friendly description of the Service.
- synchronous: When an Operation is run, if it is able to execute rapidly it will run to completion before sending the results back. However some Operations can take longer and rather than the block the rest of the system from running, they start running and return straight away. The system can then periodically check these running jobs to determine if they have finished successfully. Setting this variable to false, will declare that the Operation runs in this way. If this value is not set, then it will be assumed to be true and the Operation runs synchronously.
- operations: An array of Operation objects that the Service can perform.
<a href="#operation">Operation</a>
- operation_id (required): The name for the Operation.
- summary (required):
- so:description (required):
- parameter_set (required): The ParameterSet.
<a href="#parameterset">ParameterSet</a>
The list of Parameters is contained within a ParameterSet along with hints on how to group them together to display to the user.
- parameters: This is an array of Parameter objects.
- groups: This is an array of strings listing all of the available groups for this set of Parameters.
<a href="#parameter">Parameter</a>
- so:name: The user-friendly name of the parameter for displaying to a user. If this is not set, then the value for the param key will be used.
- param (required): The programmatic name of the parameter. If the name is not set, then this value will be used for displaying to the user.
- so:description (required): The description of the parameter to display to the user.
- default_value: The default value of the parameter.
- current_value (required): The current value of the parameter.
- type (required): This can take one of:
- string
- number
- integer
- boolean
- array
- grassroots_type (required): A number to describe the type of the Parameter. The values, along with their C definition, are shown below:
C definition | JSON value | Description |
---|---|---|
PT_BOOLEAN | xsd:boolean | The variable can be true or false. |
PT_SIGNED_INT | params:signed_integer | The variable is a non-negative integer. |
PT_UNSIGNED_INT | params:unsigned_integer | The variable is an integer. |
PT_NEGATIVE_INT | params:negative_integer | The variable is a negative integer. |
PT_SIGNED_REAL | xsd:double | The variable is a number. |
PT_UNSIGNED_REAL | params:unsigned_number | The variable is a non-negative number |
PT_STRING | xsd:string | The parameter is a general string. |
PT_FILE_TO_WRITE | params:output_filename | The parameter is the name of an output file. |
PT_FILE_TO_READ | params:input_filename | The parameter is the name of an input file. |
PT_DIRECTORY | params:directory | The parameter is the name of a directory. |
PT_CHAR | params:character | The parameter is a single ASCII character. |
PT_PASSWORD | params:password | The parameter is a password. |
PT_KEYWORD | params:keyword | The parameter is a keyword meaning it will be set of the user chooses to run a keyword search. |
PT_LARGE_STRING | params:large_string | The parameter is a string that can potentially get large in size. This is a hint to the Client to use a multi-line text box as opposed to a single one. |
PT_JSON | params:json | The parameter is a JSON fragment. |
PT_TABLE | params:tabular | The parameter holds tabular data with configurable row and column delimiters. These default to a newline and a comma respectively. |
PT_FASTA | params:fasta | The parameter holds a string of FASTA sequence data. |
enum: If the Parameter can take only take one of set of restricted values, these can be specified as an array here. The elements in this array have two fields:
- value: The programmatic value that the Parameter will be set to.
- so:description: The user-friendly name of the parameter for displaying to a user. If this is not set, then the value for the value will be used instead.
An example of this is:
"enum": [{ "so:description": "Use Raw", "value": "z" },{ "so:description": "Use Zip", "value": "zip" },{ "so:description": "Use GZip", "value": "gz" }]which indicate that the Parameter can take 1 of 3 possible values, "z", "zip" or "gz", and the values to show to the user are "Use Raw", "Use Zip" and "Use GZip".
- level: This is a number used to determine whether to show a Parameter to a user. The system defines 3 levels of Parameter; beginner, intermediate and advanced. The user can then choose which level of variables that they want displayed in their interface of choice. The values for the 3 levels are:
- beginner
- intermediate
- advanced
If a Parameter is to displayed for all levels, then the level value can be set to all.
These values can be mixed together. For example if you wanted a parameter to be displayed in just the beginner level then you would set this value to "beginner". If you wanted it displayed at the intermediate and advanced level, the value would be "intermediate advanced"
- group: If set, this specifies which of the groups listed in the ParameterSet's groups that this Parameter belongs to and is detailed in the ParameterGroup section below.
<a href="#parametergroup">ParameterGroup</a>
A ParameterGroup is a way of classing parameters together in a logical set. For example, a ParameterGroup called Address could contain Parameters for a house number, road name and town. It is used to give a hint to the user interface to display these parameters together to be more user-friendly.
Credentials
The Credentials object is used if there is access to some form of restricted content or Services needed.
- name: The name of the handler or authentication provider .
- url: The web address of the authentication provider.
- key: If using OAuth2, this is the client key token.
- secret: If using OAuth2, this is the client secret token.
- username: The encrypted username to use.
- password: The encrypted password to use.
Provider
This is the object that describes the entity or entities that are providing a given Service. Each Service will specify one of of these. Each one of these is an institution hosting a Grassroots server and used the SchemaOrg Organization type. If there is a single provider for the given Service then the key used will be provider containing the keys listed below. If the Service has been federated then the key will be providers whose value will be an array of objects with the keys listed below.
- so:name (required): The name of the Provider which will be displayed to the user.
- so:url: A web address for more information about the Provider.
- so:description (required): A description of the Provider.
- so:logo: An image to represent the Provider that will be displayed to users and other federated Servers.
So an example of specifying a single Provider for a Service is:
Whereas multiple providers would be specified using the providers key such as:
WebService
- url (required): The url to call for this webservice.
- format: How the webservice parameters will be set. This can be one of:
- get: The webservice will be called using a GET request.
- post: The webservice will be called using a POST request.
- json: The webservice will be called using a POST request where the content of the request body is a json fragment.
<a href="#resource">Resource</a>
A Resource object describes a location and a piece of data such as a file, url, etc.
- protocol (required): The class for this Resource which will determine how to access this Resource. These use the Handlers available within the system and the currently available options are:
- file: The Resource is a file or directory.
- http: The Resource is an http-based web address.
- https: The Resource is a secure https-based web address.
- irods: The Resource is an iRODS data object, collection or zone.
- dropbox: The Resource is a path to a Dropbox object.
- inline: The Resource is the raw data specified in the value field.
- value (required): The protocol-dependent value of how to access the object.