Semantics are objects that are used to create "custom states" for Components within your status page, in case more specific state information should be conveyed beyond the basic states built into Hund (i.e. Operational, Degraded, Outage, Pending).
A Semantic can be applied to any state, which will both rename and recolor the state according to the Semantic. This affects both the display of current state on your status page, as well as the historical timeline.
Semantics can be applied by certain supporting Watchdogs, such as Manual and Webhook.
Issues and Updates can also accept a Semantic in conjunction with their state overrides. Similar to a state override, Semantic overrides will affect the display of ongoing state on your status page for the duration of the overriding Issue/Update.
Creating a Semantic
From the Beta Dashboard (accessible from the link at the top of your status page's Classic Dashboard), navigate to the "Semantics" section, and click "New Semantic."
Essential Fields
From here, choose a name for your Semantic that briefly describes it. This name will show up on your status page when a Component is experiencing the Semantic, either by Watchdog or Issue.
Choose a color that will also be used on your status page where color-coding occurs, such as on the main status page, and the component-specific page when clicked-through. The color you choose will be slightly adjusted when displayed both in the dashboard, as well as your status page, for optimal readability.
Optional Fields
Optionally, you can choose an icon which will also be displayed next to Components on your status page.
You can also choose a Default State that will underlie the Semantic when a state is not already present by another mechanic. Primarily, this option will only be used by Webhook watchdogs, particularly when a semantic parameter is given in a webhook call, with no status parameter.
While normally auto-generated from the given name, you may also set an alphanumeric Slug that can be used to reference the Semantic in the REST API, or in Webhooks.
Description Fields
Finally, you must set a few additional strings that will be displayed on your status page, and in notifications. Each of these fields (including the Semantic's name) can be given in multiple languages for multilingual status pages, by changing the "Input Language" selector of the dashboard.
Status Page Heading is a description of this Semantic when shown in the "Status Bar" of your status page, or the page of a specific Component (e.g. "Operating Normally", "Experiencing Downtime", etc.). This should be written in present tense.
Historical Entry Heading is shown in the heading of the historical entry on your status page's History section (e.g. "Degraded Service", "Outage", etc.). This should be written in past tense.
Notification Description is used in notifications, and should be given as a sentence fragment that will come after the name of the Component in the notification when entering the Semantic (e.g. "is degraded", "has gone down" for Degraded and Outage states, respectively; and "has come back up" when entering Operational from a suboperational state).
Advanced Fields
Severity is an integer that denotes how "severe" this Semantic is. Smaller (including negative) values are considered more severe. This field is primarily used to order Semantics, and choose a predominant Semantic when a Component is under multiple Semantics (e.g. when multiple Issues are active with Semantic Overrides).
Historical Grouping decides whether to group events with this Semantic with other events of similar underlying state (i.e. suboperational vs. operational) in your status page's historical timeline.
Create Operational Historical Entries decides whether to emit historical entries for events with this semantic, particularly when the underlying state is Operational. By default, operational states are not recorded explicitly in history, since it is assumed that streaks of Operational status are typical and expected, and therefore and do not need to be shown as events in history.
Using a Semantic
Via Watchdogs
Once created, a Semantic can be used by any Manual or Webhook watchdog.
In the case of a Manual watchdog, navigate to the Component in the Components section of the Beta Dashboard, and select a Semantic.
For Webhooks, supply the semantic query parameter in the webhook call, with a value of either the Semantic's ID, or its slug.
Via Issues and Updates
Issues and Updates can also override their affected Components to take on a Semantic, by setting a "Semantic Override" when creating/revising an Issue or Update from the Beta Dashboard. This works similarly to a state override, and can be used in conjunction with a state override.
The Semantic Override will take precedence over the State Override when displayed on your status page, but the State Override will still decide if the Issue/Update will negatively affect percent-uptime calculations.