Define locations & location sets

Locations are the where of your data model — the gauges, reservoirs, catchments, and grid points that every time series attaches to. They’re foundational: you declare them once, and everything else (imports, ID maps, filters, models) refers to them by id.

This guide has two halves: declaring individual locations, then grouping them into location sets so a single config line can apply to a hundred places at once.

Part 1 — Declaring locations

The Locations file is a required geoDatum followed by one location per place. Each location needs a unique id and x/y; everything else is optional.

<?xml version="1.0" encoding="UTF-8"?>
<locations xmlns="http://www.wldelft.nl/fews" version="1.1">
  <geoDatum>WGS 1984</geoDatum>
  <location id="RiverGauge_01" name="River Gauge at Town Bridge">
    <shortName>TownBr</shortName>
    <x>4.895</x>
    <y>52.370</y>
    <z>2.0</z>
  </location>
</locations>

The fields you’ll reach for most:

Field	Role
`id` (attribute)	The internal id every other file references. Must be unique.
`name` (attribute)	Human-readable name shown in the UI.
`shortName`	Compact label for chart legends.
`x`, `y`, `z`	Coordinates, interpreted in the file’s `geoDatum`. `x`/`y` required.
`parentLocationId`	Makes this an (invisible) child of another location; children are auto-selected with the parent.
`visibilityPeriod`	Time-limit when the location appears in the UI — good for decommissioned sites.

Part 2 — Grouping with location sets

A location set is a named group you can refer to instead of listing locations one by one. Its power is reuse: an import, a filter, and a model can all target AllDischargeGauges, and adding a gauge to that set updates all three at once.

A locationSet has an id and defines its members one of several ways. Here are the four you’ll actually use:

List member ids directly. Simple and obvious for small, stable groups:

<locationSets xmlns="http://www.wldelft.nl/fews" version="1.1">
  <locationSet id="AllDischargeGauges">
    <locationId>RiverGauge_01</locationId>
    <locationId>RiverGauge_02</locationId>
  </locationSet>
</locationSets>

Build a set out of other sets with locationSetId — combine and reuse without re-listing:

<locationSet id="AllGauges">
  <locationSetId>DischargeGauges</locationSetId>
  <locationSetId>LevelGauges</locationSetId>
</locationSet>

For hundreds of locations, don’t hand-write them — point the set at a CSV, shapefile, GeoJSON, GeoPackage, or database table. The file supplies the members (and can carry attributes):

<locationSet id="AllGauges">
  <csvFile>
    <file>gauges.csv</file>
    <geoDatum>WGS 1984</geoDatum>
  </csvFile>
</locationSet>

The equivalent elements for other sources are esriShapeFile, geoJsonFile, geoPackageFile, and table.

Select members by rule instead of by name. constraints supports id- and attribute-based tests plus boolean logic, so the set updates itself as locations change:

<locationSet id="RiverGaugesInBasinX">
  <locationId>*</locationId>
  <constraints>
    <allValid>
      <idStartsWith>
        <startsWith>RiverGauge_</startsWith>
      </idStartsWith>
      <attributeTextEquals>
        <id>BASIN</id>
        <equals>X</equals>
      </attributeTextEquals>
    </allValid>
  </constraints>
</locationSet>

Selectors include idStartsWith / idEndsWith / idContains, attributeExists, attributeTextEquals / attributeTextContains, and the combinators not / anyValid / allValid.

Location attributes

Constraints and displays often key off attributes — arbitrary properties like BASIN, RIVER, or OWNER attached to a location. In this schema, attributes come in through a location set, not inline on <location>: the columns of a csvFile, the fields of an esriShapeFile, or a dedicated attributeFile attached to the set. Once attributes exist, attributeTextEquals and friends can select on them, which is what makes dynamic sets useful.

Common patterns

Small system: a hand-written Locations file plus explicit-list sets. Clear and low-ceremony.
Large system: keep locations and their attributes in a CSV or shapefile, load them via a file-based set, and define working sets by constraint. You maintain data, not XML.
Layered sets: compose broad sets from narrow ones (AllGauges = DischargeGauges + LevelGauges) so each location is listed once.

Gotchas

Duplicate location ids break references silently — ids must be unique across the Locations file. (A set can opt into skipDuplicateIds when merging sources, but source data should still be clean.)
Referencing an undefined set. An import or filter naming a locationSetId that isn’t defined won’t resolve. Define the set first.
geoDatum and coordinate datum must agree. Coordinates are interpreted in the declared datum; the wrong datum puts locations in the wrong place.
Empty sets. A set that resolves to zero locations is usually a mistake (bad constraint or missing source). allowEmptyLocationSets exists to permit it deliberately — don’t set it just to silence the symptom.
A higher-versioned file wins. Check for a sibling like Locations 1.01 default.xml if edits aren’t taking. See how FEWS finds a file.

Verify it worked

Open the FEWS Explorer and confirm your locations appear on the map in the right places (datum check).
Use the set somewhere — point a filter or an import at your locationSetId and confirm it resolves to the locations you expect.
For constraint-based sets, temporarily list the set in a filter and eyeball the members. If it’s empty or wrong, check the attribute/id the constraint tests actually exists on those locations.