General Syntax of Policies

Overview

In Clavata.ai, a Policy defines the guidelines the system follows to analyze and classify content. Policies can serve various purposes, including flagging content that should be avoided on your platform, detecting and categorizing content, and streamlining your moderation process for greater efficiency.

Policies are written in clear, readable terms, and are used to classify text and image content. Because Policies are at the center of how Clavata.ai works, it’s crucial to understand how to write, read, and manage your Policies effectively.

This guide provides an overview of the core elements of Policy syntax.

Jump to:

Conditions and Rule Writing

Labels

• Labels, must have a name, and can optionally have a risk level or action. 
• All Rules and content within a Label are enclosed in curly brackets. 

Example structure using the LABEL nomenclature:

LABEL "label name": "section risk or action" {
    “signal” [OPERATOR] “signal”
}

Context Conditions

• Context Conditions are enclosed in hard brackets. They have one Signal on either side of an Operator. 
  • Operators are predefined words used within Context Conditions to define relationships between Signals.

Example structure:

“signal” [OPERATOR] “signal”

Connecting Conditions

• Connecting Conditions are not enclosed in any punctuation, but the Rules within them are enclosed in curly brackets.
  • The Rules and Signals within a Label are subject to their own punctuation requirements, dependent on how they are used.
• Connecting Conditions are referred to in all capital letters in documentation as a matter of preference, but they are not case sensitive. 

Example structure:

ANY (
    "signal"
    )
AND ANY (
    "signal"
    "signal"
    )

Match Conditions

• Match Conditions follow individual syntax:
  • Exact Match is written as =("signal")
  • Fuzzy Match is written as ~(“signal”)
  • Sentiment Match is written as SENTIMENT("signal") finds negative language).
• Note: when using Signal Lists with Match Conditions, the syntax remains the same but the signals are listed on individual lines. Refer to the Signals section for more details. 

UNLESS Conditions

• UNLESS Conditions apply to the Label immediately preceding it. 
• The UNLESS Conditions are not enclosed in any punctuation, but the Rules within them are enclosed in curly brackets.
  • Individual Rules are subject to their own punctuation requirements.
• UNLESS Conditions are referred to in all capital letters in documentation as a matter of preference, but they are not case sensitive. 

Example structure:

LABEL "label name" { 
    "signal" [OPERATOR] "signal"
UNLESS {
    "signal"
 }
}

Priority

Priority allows you to specify hierarchies when it comes to your Labels. This allow you say if there are two labels that come back as true then prefer one over the other. If the system returns the Dog label and the Cat label, then only return Dog from the system. This is useful if you plan on doing API response logic.

Top-Level Priority

You can set priority at the top of your policy. This does not need to include every label within a policy but should include the ones you want to add to your hierarchy.

PRIORITY: "Mature" > "R" > "PG-13" > "PG"
LABEL "Mature" {
    "Mature content"
}
LABEL "R" {
    "R rated content"
}

Label-Level Priority

This works functionally the same as the top but you are setting the priority in an UNLESS block.

LABEL "Mature" {
    "Mature content"
}
LABEL "R" {
    "R rated content"
    UNLESS -> "Mature"
}

Duplicate Priorities

Duplicating priority logic will result in an error that has to be fixed before being able to save your policy.

PRIORITY: "Mature" > "R" > "PG-13" > "PG"
LABEL "Mature" {
    "Mature content"
}
LABEL "R" {
    "R rated content"
    UNLESS -> "Mature"
}

Signals

• Signals can be a single word or multiple words.
• Each Signal must always be enclosed in quotation marks. 
  • Example: "signal"
• Signal Lists must have each Signal in the list enclosed in quotation marks.
• Signal Lists are always paired with a Condition and therefore are enclosed in parentheses.

Example structure:

ANY (
    "dog"
    "cat"
    "pony"
    )

General Punctuation

This section provides information about the use of capitalization/case-sensitivity  and general punctuation for Policies.

Case Sensitivity

• No components of Policies are case-sensitive. 
• In documentation, Conditions are referred to in full capitalization and Signals are shown in lowercase for readability, but this is not required.

Rules on Separate Lines

• Each Rule must be entered on a new line. 

Example structure:

LABEL "label name": "risk or action" {
    "signal" [OPERATOR] "signal" ← RULE
    "signal" [OPERATOR] "signal" ← RULE
    }

Commas

• You may use commas to separate Rules or Signal Lists, but it is not required. This is purely a matter of style preference.

Indentations

• Indenting Labels and Rules is not required, but we recommend doing so as it makes your Policies significantly tidier and easier to read.

Comments

• You can add comments to your Policies using the # symbol. 
• Anything following the # on a line will be ignored by the system.

Example:

# This is a comment

Logical Wording

• Rules should be written in a way that logically connects the Signals, ensuring the Rule forms a clear and meaningful phrase or sentence.
  • This is particularly relevant to Context Conditions. 
    • For example: "misinformation" [ABOUT] "elections" uses the [ABOUT] Operator. Notice that it reads naturally with the surrounding Signals.

Need more help? Contact our support team at support@clavata.ai