Any region that can be selected for viewing on the map or plot. Includes Super Regions and Sub Regions and information about their relationships..
All regions (Super Regions and Sub Regions) MUST have a unique numeric region identifier.
Regions and Region Collections MUST NOT be identified by any of the following reserved strings:
undefined
regions
collections
metadata
Super Regions
These are top-level regions, e.g. “Western U.S.”, “Canada”. The webapp needs to be able to quickly load the list of super-regions so it can display a selector to the user. Depending on which is selected, different sub-regions may display.
Super Regions definition file MUST be named root.json.
Super Regions definition file MUST be in compliance with the schema.
Super Regions definition file MUST be pushed to the regions/ subdirectory of the incoming directory, e.g. {incomingDir}/regions/root.json.
Super Regions MAY be omitted from the Super Regions definition file if no variable are visible for the super region.
Note
In a future version of the schema, we should offer a boolean config option enabled and recommend setting it to false to omit a region.
Super Regions with no Sub Regions/Collections MAY be included in the Super Regions definition file.
Relationships with variables MUST be defined at the Super Region level, and those relationships MUST be considered inherited by all their Sub Regions.
The following Super Regions MUST always be assigned the following identifiers. This is to enable Snow Surface Properties and Snow Water Equivalent codebases to be compatible.
Western US: 26000
Alaska: 26100
Canada: 26101
Schema
{"$defs":{"SuperRegion":{"additionalProperties":false,"description":"A large region representing a top-level choice in the web application.\n\nSub-region choices will be presented depending on the super region choice.\nCoordinate reference system, water year, available variables, and more are defined\nat the super region level and inherited by sub-regions.","properties":{"longName":{"title":"Longname","type":"string"},"shortName":{"title":"Shortname","type":"string"},"shapeRelativePath":{"format":"path","title":"Shaperelativepath","type":"string"},"crs":{"description":"The coordinate reference system for this region","title":"Crs","type":"string"},"subRegionsRelativePath":{"format":"path","title":"Subregionsrelativepath","type":"string"},"subRegionsHierarchyRelativePath":{"format":"path","title":"Subregionshierarchyrelativepath","type":"string"},"variables":{"description":"The variables available for this region","patternProperties":{"^[0-9]+$":{"$ref":"#/$defs/SuperRegionVariable"}},"title":"Variables","type":"object"}},"required":["longName","shortName","shapeRelativePath","crs","subRegionsRelativePath","subRegionsHierarchyRelativePath","variables"],"title":"SuperRegion","type":"object"},"SuperRegionVariable":{"additionalProperties":false,"description":"A variable available in this super region.","properties":{"lastDateWithData":{"format":"date","title":"Lastdatewithdata","type":"string"},"default":{"type":"boolean","description":"Whether this variable is the default selection for the super region (IMPORTANT: there should only be default variable per super region)","title":"Default"},"dataValueRange":{"description":"The range of data values that the colormap will span","maxItems":2,"minItems":2,"prefixItems":[{"type":"integer"},{"type":"integer"}],"title":"Datavaluerange","type":"array"},"waterYear":{"description":"The current water year","maximum":3000,"minimum":1900,"title":"Wateryear","type":"integer"},"waterYearStartDate":{"description":"The first day of the current water year","format":"date","title":"Wateryearstartdate","type":"string"},"historicWaterYearRange":{"description":"The water years at the start and end of available climatology","maxItems":2,"minItems":2,"prefixItems":[{"exclusiveMaximum":3000,"exclusiveMinimum":1900,"type":"integer"},{"exclusiveMaximum":3000,"exclusiveMinimum":1900,"type":"integer"}],"title":"Historicwateryearrange","type":"array"},"historicSource":{"description":"The source of the climatology","title":"Historicsource","type":"string"},"geotiffRelativePath":{"format":"path","title":"Geotiffrelativepath","type":"string"},"legendRelativePath":{"format":"path","title":"Legendrelativepath","type":"string"}},"required":["lastDateWithData","default","dataValueRange","waterYear","waterYearStartDate","historicWaterYearRange","historicSource","geotiffRelativePath","legendRelativePath"],"title":"SuperRegionVariable","type":"object"}},"description":"An index of Super Regions by numeric identifier.","patternProperties":{"^[0-9]+$":{"$ref":"#/$defs/SuperRegion"}},"title":"SuperRegionsIndex","type":"object"}
Any region that is a member of a Super Region (and therefore, cannot be a Super Region itself).
Sub Regions definition files MUST be named according to the Super Region they are a member of in {superRegionId}.json, e.g. 26000.json.
Sub Regions definition files MUST be in compliance with the schema.
Sub Regions definition files MUST be pushed to the regions/ subdirectory of the incoming directory, e.g. {incomingDir}/regions/26000.json.
Sub Regions MUST be a member of a Region Collection.
Sub Regions MAY contain one or more Sub Region Collections.
Schema
{"$defs":{"SubRegion":{"additionalProperties":false,"description":"A region that is not a super region.\n\nMust be a member of a SubRegionCollection.","properties":{"longName":{"title":"Longname","type":"string"},"shortName":{"title":"Shortname","type":"string"},"shapeRelativePath":{"format":"path","title":"Shaperelativepath","type":"string"}},"required":["longName","shortName","shapeRelativePath"],"title":"SubRegion","type":"object"}},"description":"An index, with numeric keys, of sub-region definitions.","patternProperties":{"^[0-9]+$":{"$ref":"#/$defs/SubRegion"}},"title":"SubRegionsIndex","type":"object"}
Collection definition file MUST be named collections.json.
Collection definition file MUST be in compliance with the schema.
Collection definition file MUST be pushed to the regions/ subdirectory of the incoming directory, e.g. {incomingDir}/regions/collections.json.
A collection MUST contain one or many Sub Region members.
Schema
{"$defs":{"SubRegionCollection":{"additionalProperties":false,"description":"A collection of sub-regions.\n\nThis is only a definition of a collection, and does not include its relationships.\nSee SubRegionsHierarchy for relationships.","properties":{"longName":{"title":"Longname","type":"string"},"shortName":{"title":"Shortname","type":"string"}},"required":["longName","shortName"],"title":"SubRegionCollection","type":"object"}},"description":"An index, with numeric keys, of sub-region collection definitions.","patternProperties":{"^.+$":{"$ref":"#/$defs/SubRegionCollection"}},"title":"SubRegionCollectionsIndex","type":"object"}
Example
example_data/regions/collections.json
{"adm0part":{"shortName":"Country area","longName":"Country area"},"adm0":{"shortName":"Country","longName":"Country"},"adm1":{"shortName":"State","longName":"State / Country subdivision level 1"},"adm1part":{"shortName":"State area","longName":"State area"},"huc2":{"shortName":"HUC2","longName":"U.S. Hydrologic Unit Code level 2"},"huc4":{"shortName":"HUC4","longName":"U.S. Hydrologic Unit Code level 4"},"huc6":{"shortName":"HUC6","longName":"U.S. Hydrologic Unit Code level 6"},"hydro3":{"shortName":"Hydroshed3","longName":"Hydrosheds level 3"},"hydro4":{"shortName":"Hydroshed4","longName":"Hydrosheds level 4"},"hydro5":{"shortName":"Hydroshed5","longName":"Hydrosheds level 5"}}
Sub Region Hierarchy
An expression of relationships between Sub Regions. E.g.:
A State/Province may contain many multiple State subdivisions.
A HUC2 Sub Region may contain a HUC4 Sub Region Collection containing multiple HUC4 Sub Regions, each containing a collection of HUC 6 Sub Regions.
The hierarchy can be arbitrarily deep.
Sub Region Hierarchy definition files MUST be named according to the Super Region they are a member of in {superRegionId}_hierarchy.json, e.g. 26000_hierarchy.json.
Sub Region Hierarchy definition files MUST be in compliance with the schema.
Sub Region Hierarchy definition files MUST be pushed to the regions/ subdirectory of the incoming directory, e.g. {incomingDir}/regions/26000_hierarchy.json.
Schema
{"$defs":{"SubRegionsHierarchyCollection":{"additionalProperties":false,"description":"A collection of sub-regions.","properties":{"regions":{"$ref":"#/$defs/SubRegionsHierarchyCollectionRegionsIndex"}},"required":["regions"],"title":"SubRegionsHierarchyCollection","type":"object"},"SubRegionsHierarchyCollectionRegion":{"additionalProperties":false,"properties":{"collections":{"anyOf":[{"patternProperties":{"^.+$":{"$ref":"#/$defs/SubRegionsHierarchyCollectionRegionsIndex"}},"type":"object"},{"type":"null"}],"default":null,"title":"Collections"}},"title":"SubRegionsHierarchyCollectionRegion","type":"object"},"SubRegionsHierarchyCollectionRegionsIndex":{"description":"A mapping of sub-regions in a collection.","patternProperties":{"^[0-9]+$":{"$ref":"#/$defs/SubRegionsHierarchyCollectionRegion"}},"title":"SubRegionsHierarchyCollectionRegionsIndex","type":"object"},"SubRegionsHierarchyCollectionsIndex":{"description":"Collections of sub-regions identified by a unique string ID, e.g. 'huc4'.","patternProperties":{"^.+$":{"$ref":"#/$defs/SubRegionsHierarchyCollection"}},"title":"SubRegionsHierarchyCollectionsIndex","type":"object"}},"additionalProperties":false,"description":"Hierarchy of sub-region collections and their members.\n\nCollections contain sub-regions, and sub-regions may themselves contain more\ncollections. This can continue arbitrarily deep, but for user experience reasons,\nshould be kept reasonable.","properties":{"collections":{"$ref":"#/$defs/SubRegionsHierarchyCollectionsIndex"}},"required":["collections"],"title":"SubRegionsHierarchy","type":"object"}
Region Shapes definition files MUST be named according to their unique region identifier, e.g. 26000.geojson.
Region Shapes definition files MUST be , in compliance with the schema.
Region Shapes definition files MUST be pushed to the regions/shapes/ subdirectory of the incoming directory.
Region Shapes definition files MUST be organized in to sub-directories based on the first two digits of their unique region identifier, e.g. {incomingDir}/regions/shapes/26/26000.geojson.
Region Shapes MUST be provided for each defined Super Region and Sub Region.