Zaloguj się
Nowe zgłoszenie
Dokumentacja dla programistów›Poradniki›Reguły walidacji
Dokumentacja dla programistów

Reguły walidacji

PoradnikiDokumentacja API
Aktualizacja 2026-09-06

Dostępne tylko w wersji API 2026-07 i nowszych

Reguły walidacji pozwalają zadbać o jakość danych na tablicach monday.com przez określenie ograniczeń dotyczących wartości w kolumnach. W przeciwieństwie do kolumn wymaganych, które oznaczają kolumnę jako obowiązkową, reguły walidacji obsługują operatory porównania, zakresy wartości i logikę warunkową. Aby dowiedzieć się więcej o tej funkcji w interfejsie monday.com, zobacz Walidacje danych.

W tym przewodniku poznasz API reguł walidacji - od podstawowych ograniczeń po reguły warunkowe. Po jego przeczytaniu będziesz umieć programowo egzekwować reguły biznesowe, takie jak „kwoty muszą wynosić co najmniej 5” lub „jeśli status to Done, opis musi być uzupełniony”.

Kluczowe pojęcia

Jak działają reguły walidacji

Reguła walidacji składa się z dwóch części:

Część Wymagana Opis
then Tak Ograniczenie, które musi być spełnione. Określa, jak powinna wyglądać wartość w kolumnie.
if Nie Warunek, który uruchamia regułę. Jeśli go podasz, ograniczenie then będzie obowiązywać tylko po spełnieniu warunku if.

Reguły bez klauzuli if to reguły walidacji - obowiązują zawsze. Reguły z klauzulą if to reguły warunkowe - obowiązują tylko po spełnieniu warunku.

Egzekwowanie reguł

Reguły walidacji są egzekwowane zarówno w interfejsie monday.com, jak i przez API. Gdy tworzysz lub aktualizujesz elementy za pomocą mutacji takich jak create_item, change_simple_column_value lub change_column_values, API sprawdza aktywne reguły walidacji i odrzuca żądania, które je naruszają, zwracając błąd DATA_VALIDATIONS_ERROR (kod statusu 422).

Odpowiedź błędu zawiera informacje o kolumnach, które nie przeszły walidacji:

{
  "errors": [
    {
      "message": "data_validation_error",
      "extensions": {
        "code": "DATA_VALIDATIONS_ERROR",
        "status_code": 422,
        "error_data": [
          {
            "itemId": null,
            "columnIds": ["numeric_mm1pddwd"],
            "message": "'Amount' must be at least [5]"
          }
        ]
      }
    }
  ]
}

Związek z kolumnami wymaganymi

Reguły walidacji i kolumny wymagane to osobne funkcje, które mogą działać jednocześnie na tej samej tablicy:

  • Kolumny wymagane (add_required_column / remove_required_column) oznaczają kolumnę jako obowiązkową. Kolumna musi mieć wartość, ale nie określa się, jaka ma to być wartość.
  • Reguły walidacji (create_validation_rule / update_validation_rule / delete_validation_rule) określają, jakie wartości są akceptowane.

Obie funkcje pojawiają się w odpowiedzi na zapytanie validations - kolumny wymagane w required_column_ids, a reguły w rules.

Wymagania wstępne

  • Token uwierzytelniający API
  • Identyfikator tablicy (znajdziesz go w adresie URL: monday.com/boards/{board_id})
  • Znajomość identyfikatorów kolumn na tablicy (wykonaj zapytanie boards → columns → id)
  • Żądania muszą zawierać nagłówek API-Version: 2026-07
  • Konto monday.com w planie Pro lub Enterprise

Tworzenie pierwszej reguły

Reguła walidacji

Utwórzmy regułę, która wymaga, aby w kolumnie statusu znajdowała się jedna z dwóch określonych wartości (indeksy etykiet 1 i 2):

mutation {
  create_validation_rule(
    id: 1234567890,
    type: board,
    rule: {
      then: {
        operator: AND,
        groups: [{
          operator: ANY_OF,
          column_id: "status",
          compare_value: [1, 2]
        }]
      }
    }
  ) {
    id
    if
    then
  }
}

Odpowiedź zawiera wygenerowany identyfikator reguły:

{
  "data": {
    "create_validation_rule": {
      "id": "cd7f1b7b-452e-40d3-886c-346184ffee7e",
      "if": null,
      "then": {
        "operator": "AND",
        "groups": [
          {
            "operator": "ANY_OF",
            "column_id": "status",
            "compare_value": [1, 2]
          }
        ]
      }
    }
  }
}

Ważne informacje: - Klauzula then wymaga pola operator (AND lub OR) oraz tablicy groups zawierającej ograniczenia. - Każde ograniczenie dotyczy kolumny wskazanej przez column_id i zawiera operator porównania operator oraz opcjonalne pole compare_value. - Reguły walidacji bez klauzuli if zwracają null w polu if. - Zwrócone id to identyfikator UUID używany przy aktualizowaniu i usuwaniu reguł.

Ograniczenie liczbowe

Wymagaj, aby wartość w kolumnie liczb wynosiła co najmniej 5:

mutation {
  create_validation_rule(
    id: 1234567890,
    type: board,
    rule: {
      then: {
        operator: AND,
        groups: [{
          operator: GREATER_THAN_OR_EQUALS,
          column_id: "numbers0",
          compare_value: [5]
        }]
      }
    }
  ) {
    id
    then
  }
}

Ograniczenie zakresu dat

Wymagaj, aby data w kolumnie mieściła się w określonym zakresie:

mutation {
  create_validation_rule(
    id: 1234567890,
    type: board,
    rule: {
      then: {
        operator: AND,
        groups: [{
          operator: BETWEEN,
          column_id: "date0",
          compare_value: ["2026-01-01", "2026-12-31"]
        }]
      }
    }
  ) {
    id
    then
  }
}

Ograniczenie tekstowe

Wymagaj, aby kolumna tekstowa zawierała określony fragment tekstu:

mutation {
  create_validation_rule(
    id: 1234567890,
    type: board,
    rule: {
      then: {
        operator: AND,
        groups: [{
          operator: CONTAINS_TEXT,
          column_id: "text0",
          compare_value: ["REQ-"]
        }]
      }
    }
  ) {
    id
    then
  }
}

Reguły warunkowe

Reguły warunkowe używają klauzuli if, aby określić, kiedy obowiązuje ograniczenie then. Dzięki temu możesz tworzyć reguły takie jak „jeśli status to Done, opis musi być uzupełniony”.

Podstawowa reguła warunkowa

mutation {
  create_validation_rule(
    id: 1234567890,
    type: board,
    rule: {
      if: {
        operator: AND,
        groups: [{
          operator: ANY_OF,
          column_id: "status",
          compare_value: [1]
        }]
      },
      then: {
        operator: AND,
        groups: [{
          operator: IS_NOT_EMPTY,
          column_id: "text0"
        }]
      }
    }
  ) {
    id
    if
    then
  }
}

👍 IS_NOT_EMPTY w regułach warunkowych

Operator IS_NOT_EMPTY jest dostępny tylko w regułach warunkowych (regułach z klauzulą if). Nie można go używać w samodzielnych regułach walidacji. Możesz użyć go zarówno w klauzuli if, jak i then - na przykład, aby uruchomić regułę, gdy jedna kolumna nie jest pusta, albo wymagać wartości w kolumnie po spełnieniu warunku.

Wiele ograniczeń w klauzuli then

Reguły warunkowe mogą jednocześnie egzekwować kilka ograniczeń. Jeśli warunek zostanie spełniony, wymagaj uzupełnienia zarówno kolumny liczb, jak i kolumny daty:

mutation {
  create_validation_rule(
    id: 1234567890,
    type: board,
    rule: {
      if: {
        operator: AND,
        groups: [{
          operator: ANY_OF,
          column_id: "priority",
          compare_value: [1]
        }]
      },
      then: {
        operator: AND,
        groups: [
          {
            operator: IS_NOT_EMPTY,
            column_id: "numbers0"
          },
          {
            operator: IS_NOT_EMPTY,
            column_id: "date0"
          }
        ]
      }
    }
  ) {
    id
    if
    then
  }
}

Aktualizowanie i usuwanie reguł

Aktualizowanie reguły

Użyj update_validation_rule z identyfikatorem reguły. Musisz podać pełną definicję reguły - częściowe aktualizacje nie są obsługiwane:

mutation {
  update_validation_rule(
    id: 1234567890,
    type: board,
    rule_id: "cd7f1b7b-452e-40d3-886c-346184ffee7e",
    rule: {
      then: {
        operator: AND,
        groups: [{
          operator: GREATER_THAN_OR_EQUALS,
          column_id: "numbers0",
          compare_value: [10]
        }]
      }
    }
  ) {
    id
    if
    then
  }
}

Usuwanie reguły

mutation {
  delete_validation_rule(
    id: 1234567890,
    type: board,
    rule_id: "cd7f1b7b-452e-40d3-886c-346184ffee7e"
  ) {
    id
  }
}

Mutacja zwraca dane usuniętej reguły.

Odczytywanie reguł walidacji

Wykonaj zapytanie do punktu końcowego validations, aby wyświetlić wszystkie reguły walidacji i kolumny wymagane na tablicy:

query {
  validations(id: 1234567890) {
    required_column_ids
    rules
  }
}

Pole rules zwraca obiekt JSON, w którym każdy klucz jest identyfikatorem reguły, a każda wartość zawiera definicję reguły:

{
  "data": {
    "validations": {
      "required_column_ids": null,
      "rules": {
        "80d2c9d3-c93d-40be-9d34-b611241345b5": {
          "then": {
            "operator": "AND",
            "groups": [{
              "operator": "GREATER_THAN_OR_EQUALS",
              "column_id": "numbers0",
              "compare_value": [5]
            }]
          }
        },
        "31933592-171a-47ae-93a5-7a1c214fc9a3": {
          "if": {
            "operator": "AND",
            "groups": [{
              "operator": "ANY_OF",
              "column_id": "status",
              "compare_value": [1]
            }]
          },
          "then": {
            "operator": "AND",
            "groups": [{
              "operator": "IS_NOT_EMPTY",
              "column_id": "text0",
              "compare_value": []
            }]
          }
        }
      }
    }
  }
}

📘 UWAGA

W odpowiedzi na zapytanie reguły warunkowe zawierają klucze if i then. Reguły walidacji bez warunku mają tylko klucz then (klucz if jest nieobecny, a nie ustawiony na null). Różni się to od odpowiedzi mutacji, w której pole if ma jawnie wartość null.

Obsługiwane operatory według typu kolumny

Obsługa operatorów znacznie różni się w zależności od typu klauzuli (zwykłe reguły, klauzula IF reguły warunkowej lub klauzula THEN reguły warunkowej). Nie wszystkie operatory działają ze wszystkimi typami kolumn. Sprawdź tabele poniżej, aby znaleźć operatory obsługiwane w konkretnym przypadku.

Zwykłe reguły walidacji (bez klauzuli if)

Zwykłe reguły obsługują najbardziej ograniczony zestaw operatorów. Kolumna może mieć tylko JEDNĄ zwykłą regułę z JEDNYM ograniczeniem:

Typ kolumny Obsługiwane operatory
status ANY_OF, NOT_ANY_OF
dropdown ANY_OF, NOT_ANY_OF
rating ANY_OF, NOT_ANY_OF
numbers NOT_EQUALS, GREATER_THAN, GREATER_THAN_OR_EQUALS, LOWER_THAN, LOWER_THAN_OR_EQUAL
date NOT_EQUALS, GREATER_THAN, GREATER_THAN_OR_EQUALS, LOWER_THAN, LOWER_THAN_OR_EQUAL, BETWEEN
text CONTAINS_TEXT, NOT_CONTAINS_TEXT, STARTS_WITH_TEXT
long_text CONTAINS_TEXT, NOT_CONTAINS_TEXT, STARTS_WITH_TEXT
email CONTAINS_TEXT, NOT_CONTAINS_TEXT, STARTS_WITH_TEXT
phone CONTAINS_TEXT, NOT_CONTAINS_TEXT, STARTS_WITH_TEXT
link CONTAINS_TEXT, NOT_CONTAINS_TEXT, STARTS_WITH_TEXT
country CONTAINS_TEXT, NOT_CONTAINS_TEXT, STARTS_WITH_TEXT
checkbox, people, timeline, location, week, hour, tags, file, world_clock, vote, color_picker, time_tracking, dependency (brak obsługiwanych operatorów)

Reguły warunkowe: klauzula IF

Klauzula if uruchamia regułę. Obsługuje podzbiór operatorów:

Typ kolumny Obsługiwane operatory
status ANY_OF, NOT_ANY_OF, IS_NOT_EMPTY
dropdown ANY_OF, NOT_ANY_OF, IS_NOT_EMPTY
rating ANY_OF, NOT_ANY_OF, IS_NOT_EMPTY
numbers EQUALS, NOT_EQUALS, IS_NOT_EMPTY, GREATER_THAN, GREATER_THAN_OR_EQUALS, LOWER_THAN, LOWER_THAN_OR_EQUAL
date EQUALS, NOT_EQUALS, IS_NOT_EMPTY, GREATER_THAN, GREATER_THAN_OR_EQUALS, LOWER_THAN, LOWER_THAN_OR_EQUAL, BETWEEN
text IS_NOT_EMPTY, CONTAINS_TEXT, NOT_CONTAINS_TEXT, STARTS_WITH_TEXT
long_text IS_NOT_EMPTY, CONTAINS_TEXT, NOT_CONTAINS_TEXT, STARTS_WITH_TEXT
email IS_NOT_EMPTY, CONTAINS_TEXT, NOT_CONTAINS_TEXT, STARTS_WITH_TEXT
phone IS_NOT_EMPTY, CONTAINS_TEXT, NOT_CONTAINS_TEXT, STARTS_WITH_TEXT
link IS_NOT_EMPTY, CONTAINS_TEXT, NOT_CONTAINS_TEXT, STARTS_WITH_TEXT
country IS_NOT_EMPTY, CONTAINS_TEXT, NOT_CONTAINS_TEXT, STARTS_WITH_TEXT
checkbox IS_NOT_EMPTY
people IS_NOT_EMPTY
timeline IS_NOT_EMPTY
location IS_NOT_EMPTY
week, hour, tags, file, world_clock, vote, color_picker, time_tracking, dependency (brak obsługiwanych operatorów)

Reguły warunkowe: klauzula THEN

Klauzula then egzekwuje ograniczenie po spełnieniu warunku. Obsługuje więcej operatorów:

Typ kolumny Obsługiwane operatory
status ANY_OF, NOT_ANY_OF, IS_EMPTY, IS_NOT_EMPTY
dropdown ANY_OF, NOT_ANY_OF, IS_EMPTY, IS_NOT_EMPTY
rating ANY_OF, NOT_ANY_OF, IS_NOT_EMPTY
numbers EQUALS, NOT_EQUALS, IS_NOT_EMPTY, GREATER_THAN, GREATER_THAN_OR_EQUALS, LOWER_THAN, LOWER_THAN_OR_EQUAL
date NOT_EQUALS, IS_NOT_EMPTY, GREATER_THAN, GREATER_THAN_OR_EQUALS, LOWER_THAN, LOWER_THAN_OR_EQUAL, BETWEEN
text IS_NOT_EMPTY, CONTAINS_TEXT, NOT_CONTAINS_TEXT, STARTS_WITH_TEXT
long_text IS_NOT_EMPTY, CONTAINS_TEXT, NOT_CONTAINS_TEXT, STARTS_WITH_TEXT
email IS_NOT_EMPTY, CONTAINS_TEXT, NOT_CONTAINS_TEXT, STARTS_WITH_TEXT
phone IS_NOT_EMPTY, CONTAINS_TEXT, NOT_CONTAINS_TEXT, STARTS_WITH_TEXT
link IS_NOT_EMPTY, CONTAINS_TEXT, NOT_CONTAINS_TEXT, STARTS_WITH_TEXT
country IS_NOT_EMPTY, CONTAINS_TEXT, NOT_CONTAINS_TEXT, STARTS_WITH_TEXT
checkbox IS_EMPTY, IS_NOT_EMPTY
people IS_EMPTY, IS_NOT_EMPTY
timeline IS_NOT_EMPTY
location IS_NOT_EMPTY
week, hour, tags, file, world_clock, vote, color_picker, time_tracking, dependency (brak obsługiwanych operatorów)

📘 BETWEEN dla kolumn liczb

Operator BETWEEN NIE jest obsługiwany w kolumnach numbers w żadnej klauzuli. Jest dostępny tylko dla kolumn date.

Ograniczenia i limity

Ograniczenie Opis
Jedna zwykła reguła na kolumnę Kolumna może mieć najwyżej jedną regułę walidacji bez klauzuli if. Próba dodania drugiej zwykłej reguły kończy się błędem „A column can have only one non-conditional rule”.
Jedno ograniczenie na zwykłą regułę Reguły walidacji bez klauzuli if muszą zawierać w klauzuli then dokładnie jedno ograniczenie. Nie można dodać kilku ograniczeń.
Wiele ograniczeń w regule warunkowej Reguły warunkowe (z klauzulą if) mogą zawierać w klauzuli then kilka ograniczeń połączonych operatorem AND lub OR. Klauzula if musi zawierać dokładnie jedno ograniczenie.
Nie można łączyć typów reguł Kolumna nie może mieć jednocześnie zwykłej reguły walidacji i reguły warunkowej. Próba dodania obu kończy się błędem „A column cannot have both conditional and non-conditional rules”.
Tylko plany Pro i Enterprise Reguły walidacji wymagają planu Pro lub Enterprise. Konta Free/Standard otrzymują błąd UserUnauthorizedException, którego przyczyna zawiera „data_validation_rules” lub „required_columns”.
Kolumny obsługujące wymagane wartości a kolumny obsługujące reguły Kolumnę można oznaczyć jako wymaganą, nawet jeśli nie obsługuje żadnych reguł walidacji (np. timeline, location). Zobacz Kolumny wymagane i Obsługa operatorów.
Egzekwowanie w interfejsie i API Reguły są egzekwowane zarówno w interfejsie monday.com, jak i przez API. Żądania API naruszające reguły zwracają DATA_VALIDATIONS_ERROR (kod statusu 422) wraz z informacjami o kolumnach, które nie przeszły walidacji.

Formaty wartości porównywanych

Format tablicy compare_value zależy od typu kolumny i operatora. Dokładnie przestrzegaj poniższych zasad - API rygorystycznie sprawdza format:

Operatory oparte na etykietach (status, dropdown, rating)

Używaj indeksów etykiet (liczb całkowitych), a nie ich nazw:

# ✅ DO: Use label index
compare_value: [1, 2]

# ❌ DON'T: Use label name
compare_value: ["Done", "In Progress"]

Wartości liczbowe

Do porównania użyj jednej liczby, a dla operatora BETWEEN - dwóch liczb (nie jest obsługiwany w kolumnach liczb):

Operator compare_value Uwagi
GREATER_THAN, GREATER_THAN_OR_EQUALS, LOWER_THAN, LOWER_THAN_OR_EQUAL, EQUALS, NOT_EQUALS [5] Pojedyncza wartość liczbowa

Wartości dat i osi czasu

Ważne: Format daty w porównaniach zależy od operatora:

Operator compare_value Uwagi
BETWEEN ["2026-01-01", "2026-12-31"] Dwa ciągi znaków z datami w formacie YYYY-MM-DD, bez prefiksu EXACT
GREATER_THAN, GREATER_THAN_OR_EQUALS, LOWER_THAN, LOWER_THAN_OR_EQUAL, NOT_EQUALS ["EXACT", "2026-01-01"] Wymagane: dodaj prefiks "EXACT", a następnie datę w formacie YYYY-MM-DD
EQUALS ["EXACT", "2026-01-01"] Tak jak w przypadku pozostałych porównań - dodaj prefiks "EXACT"

Kolumny osi czasu używają tego samego formatu co kolumny daty.

Operatory oparte na tekście

Użyj jednej wartości tekstowej:

Operator compare_value Uwagi
CONTAINS_TEXT, NOT_CONTAINS_TEXT, STARTS_WITH_TEXT ["search term"] Pojedyncza wartość tekstowa

Operatory sprawdzające, czy wartość jest pusta lub niepusta

Pomiń compare_value albo przekaż pustą tablicę:

Operator compare_value
IS_EMPTY, IS_NOT_EMPTY (pomiń) lub []

Kolumny wymagane

Kolumny wymagane oznaczają pole jako obowiązkowe, ale nie określają ograniczeń dotyczących jego wartości. Wymagana kolumna może nadal przyjmować dowolną wartość.

Typy kolumn obsługujące wymagane wartości

Następujące 14 typów kolumn można oznaczyć jako wymagane za pomocą add_required_column:

  • status, dropdown, numbers, date, timeline, people, text, long_text, email, phone, link, rating, country, location

Typy kolumn, których NIE można oznaczyć jako wymagane

Następujących typów kolumn nie można oznaczyć jako wymaganych (API zwraca błąd „Column ids are unsupported due to their types”):

  • checkbox, week, hour, tags, file, world_clock, vote, color_picker, time_tracking, dependency, button, formula, mirror, lookup, auto_number, integration, doc, progress, subtasks, vote

Kolumny obsługujące wymagane wartości, ale nieobsługujące reguł

Niektóre kolumny można oznaczyć jako wymagane, ale nie obsługują żadnych reguł walidacji:

  • timeline - można oznaczyć jako wymaganą, ale odrzuca wszystkie operatory w zwykłych regułach oraz w klauzulach IF i THEN.
  • location - można oznaczyć jako wymaganą, ale odrzuca wszystkie operatory w zwykłych regułach oraz w klauzulach IF i THEN.

Obsługa błędów

Błędy walidacji danych

Gdy mutacja API narusza regułę walidacji, odpowiedź zawiera kod statusu 422 i kod DATA_VALIDATIONS_ERROR:

{
  "errors": [
    {
      "message": "data_validation_error",
      "extensions": {
        "code": "DATA_VALIDATIONS_ERROR",
        "status_code": 422,
        "error_data": [
          {
            "itemId": null,
            "columnIds": ["numeric_mm1pddwd"],
            "message": "'Amount' must be at least [5]"
          },
          {
            "itemId": null,
            "columnIds": ["text_mm1pecmq"],
            "message": "'Description' must not be empty"
          }
        ]
      }
    }
  ]
}

Ważne: pole error_data jest tablicą, a nie pojedynczym obiektem. Jedno żądanie może naruszać reguły w kilku kolumnach - przejrzyj całą tablicę, aby obsłużyć wszystkie błędy.

Błędy związane z planem

Konta bez planu Pro lub Enterprise otrzymują błąd UserUnauthorizedException:

{
  "errors": [
    {
      "message": "UserUnauthorizedException",
      "extensions": {
        "error_data": {
          "failure_reason": "ms-authorization.permissions.data_validation_rules.not_available"
        }
      }
    }
  ]
}

Zapytanie validations zwracające null

Zapytanie validations zwraca null w polu rules w dwóch przypadkach:

  1. Na tablicy nie skonfigurowano żadnych reguł.
  2. Funkcja jest niedostępna (plan Free/Standard; funkcja jest dostępna tylko w planach Pro i Enterprise).

Nie da się odróżnić tych przypadków, więc kod nie może ustalić, czy null oznacza „brak reguł”, czy „brak dostępu do funkcji”. Może być konieczne osobne sprawdzenie planu konta.

Następne kroki

Jeśli masz pytania, opublikuj je w społeczności deweloperów monday.

Mam problem z tym tematem Źródło: developer.monday.com