Rules

A rule is a collection of styling directives, primarily consisting of symbolizers combined with optional conditional statements.

  • If a conditional statement exists in a rule, then the styling directives will only be carried out if the conditional returns true. Otherwise, the rule will be skipped.

  • If no conditional statement exists in a rule, then the styling directive will always be carried out.

The types of conditional statements available to rules are:

  • Filters for attribute-based rendering

  • Scale for scale-based rendering

Rules are contained within feature styles. There is no limit on the number of rules that can be created, and there is no restriction that all rules must be mutually exclusive (as in, some rules may apply to the same features).

Syntax

The following is the basic syntax of a rule. Note that the contents of the block are not all expanded; see the other sections for the relevant syntax.

rules:
- name: <text>
  title: <text>
  filter: <filter>
  else: <boolean>
  scale: [<min>,<max>]
  symbolizers:
  - ...
  x-inclusion: <text>

where:

Property

Required?

Description

Default value

name

No

Internal reference to the feature style. It is recommended that the value be lower case and contain no spaces.

Blank

title

No

Human-readable description of what the rule accomplishes.

Blank

filter

No

Filter expression which will need to evaluate to be true for the symbolizer(s) to be applied. Cannot be used with else.

Blank (meaning that the rule will apply to all features)

else

No

Specifies whether the rule will be an “else” rule. An else rule applies when, after scale and filters are applied, no other rule applies. To make an else rule, set this option to true. Cannot be used with filter.

false

scale

No

Scale boundaries showing at what scales (related to zoom levels) the rule will be applied.

Visible at all scales

symbolizers

Yes

Block containing one or more symbolizers. These contain the actual visualization directives. If the filter returns true and the view is within the scale boundaries, these symbolizers will be drawn.

N/A

x-inclusion

No

Define if rule should be included in style for legendOnly or mapOnly (see Rendering Selection)

normal

Short syntax

When a style has a single rule inside a single feature style, it is possible to omit the syntax for both and start at the first parameter inside.

So the following complete styles are equivalent:

feature-styles:
- rules:
  - symbolizers:
    - line:
        stroke-color: '#000000'
        stroke-width: 2

line:
  stroke-color: '#000000'
  stroke-width: 2

Examples

Else filter

Using filter and else together:

rules:
- name: small
  title: Small features
  filter: ${type = 'small'}
  symbolizers:
  - ...
- name: large
  title: Large features
  filter: ${type = 'large'}
  symbolizers:
  - ...
- name: else
  title: All other features
  else: true
  symbolizers:
  - ...

In the above situation:

  • If a feature has a value of “small” in its type attribute, it will be styled with the “small” rule.

  • If a feature has a value of “large” in its type attribute, it will be styled with the “large” rule.

  • If a feature has a value of “medium” (or anything else) in its type attribute, it will be styled with the “else” rule.

Else with scale

Using filter, else, and scale together:

rules:
- name: small_zoomin
  scale: [min,10000]
  title: Small features when zoomed in
  filter: ${type = 'small'}
  symbolizers:
  - ...
- name: small_zoomout
  scale: [10000,max]
  title: Small features when zoomed out
  filter: ${type = 'small'}
  symbolizers:
  - ...
- name: else_zoomin
  scale: [min,10000]
  title: All other features when zoomed in
  else: true
  symbolizers:
  - ...
- name: else_zoomout
  scale: [10000,max]
  title: All other features when zoomed out
  else: true
  symbolizers:
  - ...

In the above situation:

  • If a feature has a value of “small” in its type attribute, and the map is a scale level less than 10,000, it will be styled with the “small_zoomin” rule.

  • If a feature has a value of anything else other than “small” in its type attribute, and the map is a scale level less than 10,000, it will be styled with the “else_zoomin” rule.

  • If a feature has a value of “small” in its type attribute, and the map is a scale level greater than 10,000, it will be styled with the “small_zoomout” rule.

  • If a feature has a value of anything else other than “small” in its type attribute, and the map is a scale level greater than 10,000, it will be styled with the “else_zoomout” rule.

Previous: Feature Styles
Next: Symbolizers