Model Instance Metadata Schema

Model instance metadata schema is a JSON file (to avoid unnecessary repetition, we call it JSON schema in the rest of this help page) that defines specific metadata for a model instance aggregation that is associated “via execute_by” relation to a model program aggregation having the JSON schema. The JSON schema file is either uploaded by the user or user selected schema file from one of the schema files available in HydroShare. In order for the users to successfully create and upload their own JSON schema, there are some requirements that need to be followed which are described below.

JSON File Formatting Requirements

Currently, HydroShare follows standard JSON schema Draft 4, requirements of which can be found here. Additionally, HydroShare uses json-editor JavaScript module to make the dynamic form generation based on the JSON schema to render the form suitable for editing metadata. The requirements related to json-editor are described below.

At the root level of the JSON schema, there must be a ‘$schema’ attribute with value (indicating the version of the JSON schema being used - ‘draft-04’) set as shown below:

{ 
"$schema": "http://json-schema.org/draft-04/schema#", 
}

Each property field must have a ‘title’ attribute which is used as a label for that form field when the form is generated from the schema.

Here is an example (Not a complete JSON schema):

"properties": 
{ "simulationType": 
   {  
   "type": "string",
   "title": "Simulation Type",
   "description": "Type of simulation used."
}

Any object type property must have the attribute ‘additionalProperties’ set to false. This is needed in order to prevent users from adding new form fields when editing metadata for model instance aggregation.

Here is an example (Not a complete JSON schema):

"modelMethod": { "modelMethod": { 
   "type": "object",
    "title": "Model Method",
    "description": "Various methods used in creating this model instance.",
    "properties": {
        "runoffCalculationMethod": {
            "type": "string",
            "title": "Runoff Calculation Method",
            "description": "Runoff calculation method used in creating this model instance.",
            "default": ""
            },
       "flowRoutingMethod": 
       {
           "type": "string",
           "title": "Flow Routing Method",
           "description": "Flow routing method used in creating this model instance.",
           "default": ""
       }
 },
 "additionalProperties": false
 }  
"type": "object",
 "title": "Model Method",
 "description": "Various methods used in creating this model instance.",
 "properties": {
 "runoffCalculationMethod": {

To use a checkbox for a boolean type field, attribute ‘format’ needs to be set to checkbox.

Here is an example (Not a complete JSON schema):

"hydrology": { 
   "type": "boolean",
   "title": "Hydrology",
   "format": "checkbox"
 }

Optionally, each property field can have the attribute ‘description’ to describe the purpose of the field which is used as help text and displayed below the form field when the form is generated based on the JSON schema.

Here is an example (Not a complete JSON schema):

"simulationType": { 
   "type": "string",
   "title": "Simulation Type",
   "description": "Type of simulation method 
}

The form generation JS module that HydroShare uses to generate a metadata editing form based on a JSON schema (i.e., json-editor), will create the form elements in the order they appear in the schema when the form is generated. The ordering of the fields in the schema could be different when it is saved to the system compared to the order in which the user specified the schema as an input. If the form fields need to be displayed in a specific order, then use the field attribute ‘propertyOrder’ to specify the order of that field in the schema. This attribute has meaning only to json-editor and not part of the JSON schema standard specification.

Here is an example (Not a complete JSON schema) where the form field ‘simulationMethod’ will appear above the form field ‘simulationPeriod’:

"simulationMethod": {
   "type": "string",
   "title": "Simulation Method",
   "description": "Type of simulation method used.",
 "propertyOrder":  1
},
"simulationPeriod": {
   "type": "string",
   "title": "Simulation Period",
   "description": "Time period used for the simulation." ,
 "propertyOrder":  2
}

Nested objects are NOT allowed - meaning a field/attribute of type ‘object’ can’t contain a sub-field/attribute of type ‘object’. We are putting this restriction in order to make the schema based form to not get too complicated. Please note that a field/attribute of type ‘object’ can still contain other fields/attributes that are NOT of type ‘object’

Here is an example of nested objects. In this example, the ‘modelMethod’ attribute is of type ‘object’ and it contains two child attributes: ‘analysisMethod’, which is of type ‘object’ (NOT allowed in HydroShare), and "flowRoutingMethod", which is of type ‘string’ (allowed in HydroShare).

"modelMethod": {
   "type": "object",
   "title": "Model Method",
   "description": "Various methods used in creating this model instance.",
      "properties": {
    "flowRoutingMethod": {
       "type": "string",
       "title": "Flow Routing Method",
       "description": "Flow routing method used in creating this model instance.",
       "default": "
     },
           "analysisMethod": {
    "type": "object",
    "title": "Analysis Method",
    "properties": {
    "classification": {
    "type": "string",
    "title": "Classification"
    },
    "estimation": {
    "type": "string",
    "title": "Estimation"
    }
    },
"additionalProperties": false
    }
      },
      "additionalProperties": false
    }

Additional Requirements related to Attribute (Key) Naming in JSON Schema:

These additional requirements/constraints for attribute name are needed for XML/RDF encoding of model instance metadata based on metadata schema.

Attribute name must consist of only alphanumeric characters.
Attribute name must start with an alphabet character

Examples of Invalid Attribute Name:

“totalLength “ : { 
}

Invalidation reason: There is a whitespace at the end

“ totalLength“ : {
}

Invalidation reason: There is a whitespace at the beginning

“total Length“ : {
}

Invalidation reason: There is a whitespace at the middle

“1totalLength “ : {
}

Invalidation reason: Starts with a number

“totalLength(meters)“ : {
}

Invalidation reason: Contains non-alphanumeric characters

Some Other Useful Remarks

Users can make a field/attribute “required” by specifying that at the root level of the JSON schema.

Here is an example (first few lines of a JSON schema are shown) where the field “modelObjective” is set to be required:

{
   "type": "object",
   "title": "SWAT Model Instance Metadata Schema",
   "$schema": "http://json-schema.org/draft-04/schema#",
   "required": [
       "modelObjective"
   ],
.
.
.
}

Users can specify a default value for a field/attribute required.

Here is an example (Not a complete JSON schema):

"modelMethod": {
   "type": "object",
   "title": "Model Method",
    "description": "Various methods used in creating this model instance.", 
   "properties": {
      "runoffCalculationMethod": {
      "type": "string",
      "title": "Runoff Calculation Method",
      "description": "Runoff calculation method used in creating this model instance.",
      "default": "Curve Number"
   }
 },
 "additionalProperties": false
 }

Users can use “enum” to make a list of controlled vocabulary from which a value may be selected for an attribute.

Here is an example (Not a complete JSON schema):

simulationType": {
    "enum": [
   "Normal Simulation",
   "Sensitivity Analysis",
   "Auto Calibration"
   ],
   "type": "string",
   "title": "Simulation Type",
   "description": "Type of simulation used.",
  "propertyOrder": 3

A Complete Metadata Schema Example

Here is a complete metadata schema example (which is a modified and summarized version of the SWAT JSON schema provided by HydroShare) highlighting the required elements as described above:

{
 "type": "object",
 "title": "SWAT Model Instance Metadata Schema",
 "$schema": "http://json-schema.org/draft-04/schema#",
 "required": [
 "modelObjective"
 ],
 "properties": {
    "modelObjective": {
       "type": "object",
       "title": "Model Objectives",
       "properties": {
          "hydrology": {
             "type": "boolean",
             "title": "Hydrology",
             "format": "checkbox",
             "propertyOrder": 1
             },
             "waterQuality": {
                "type": "boolean",
                "title": "Water Quality",
                "format": "checkbox",
                "propertyOrder": 2
                },
                "OtherObjectives": {
                   "type": "string",
                   "title": "Other objectives",
                   "propertyOrder": 3
                   }
                },
                "description": "Objectives of this SWAT model instance.",
                "propertyOrder": 1,
                "additionalProperties": false
            },
            "modelParameter": {
               "type": "object",
               "title": "Model Parameters",
               "properties": {
                  "cropRotation": {
                  "type": "boolean",
                  "title": "Crop rotation",
                  "format": "checkbox",
                  "propertyOrder": 1
            },
            "tileDrainage": {
               "type": "boolean",
               "title": "Tile drainage",
               "format": "checkbox",
               "propertyOrder": 2
            }
       },
       "description": "Various model parameters used in this model instance.",
       "propertyOrder": 2,
       "additionalProperties": false
    },
    "simulationType": {
       "enum": [
          "Normal Simulation",
          "Sensitivity Analysis",
          "Auto Calibration"
       ],
       "type": "string",
       "title": "Simulation Type",
       "description": "Type of simulation used.",
       "propertyOrder": 3
    },
    "modelMethod": {
       "type": "object",
       "title": "Model Method",
        "properties": {
           "runoffCalculationMethod": {
           "type": "string",
           "title": "Runoff Calculation Method",
           "default": "",
           "description": "Runoff calculation method used in creating this model instance.",
     "propertyOrder": 1
    },
    "flowRoutingMethod": {
    "type": "string",
     "title": "Flow Routing Method",
     "default": "",
    "description": "Flow routing method used in creating this model instance.",
    "propertyOrder": 2
    }
 },
 "description": "Various methods used in creating this model instance.",
 "propertyOrder": 4,
 "additionalProperties": false
 },
 "modelInput": {
    "type": "object",
    "title": "Model Inputs",
    "properties": {
       "watershedArea": {
          "type": "number",
          "title": "Watershed Area (in square kilometers)",
          "default": 0,
          "description": "Area of the watershed used in creating this model instance.",
          "propertyOrder": 1
          },
          "numberOfSubbasins": {
             "type": "number",
             "title": "Number of Sub-basins",
             "default": 1,
             "description": "Number of sub-basins used in creating this model instance.",
             "propertyOrder": 2
             }
        },
        "description": "Various inputs used in creating this model instance.",
        "propertyOrder": 5,
        "additionalProperties": false
    }
 },
    "description": "A sample schema for SWAT model instance metadata.",
    "additionalProperties": false
}

The following figure shows the generated metadata form in HydroShare using the above example. The user can enter values for the metadata fields in this form: