> ## Documentation Index
> Fetch the complete documentation index at: https://docs-attestly.code4source.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Conceitos básicos de ruleset

> Codifique sua política de compliance como um ruleset JSON.

Um **ruleset** é um documento JSON que descreve:

1. Quais sources consultar (e como filtrá-los).
2. Quais valores computar (counts, áreas, distâncias).
3. Quais condições devem valer para o resultado ser compliant.

Envie o ruleset inline a cada `/v1/evaluate`, ou salve uma vez no
catálogo e referencie por `name@version` depois.

## Anatomia

```json theme={null}
{
  "name": "br-rural-credit",
  "version": 1,
  "description": "Elegibilidade de crédito rural por Resolução BCB 4.943",

  "sets": {
    "indigenous_overlap": {
      "source": "funai_tis",
      "joins": [{ "intersects": { "target": "$input" } }]
    },
    "embargo_overlap": {
      "source": "ibama_embargos",
      "joins": [{ "intersects": { "target": "$input" } }]
    }
  },

  "projections": [
    {
      "id": "indigenous_area",
      "terminal": { "type": "total_area_m2", "set": "$indigenous_overlap" }
    }
  ],

  "checks": [
    {
      "id": "no_indigenous_overlap",
      "severity": "critical",
      "predicate": { "type": "exists", "set": "$indigenous_overlap" }
    },
    {
      "id": "no_embargo_overlap",
      "severity": "high",
      "predicate": { "type": "exists", "set": "$embargo_overlap" }
    }
  ]
}
```

## Os três blocos

### `sets` — quais feições considerar

Um set é ancorado em um **source** e cruzado contra `$input` (sua
geometria/identificador da request) ou outro set. Operadores de join
disponíveis:

* `intersects` — sobreposição de geometria
* `contains` / `within` — contenção total
* `covers` / `covered_by` — contenção incluindo toque de borda
* `overlaps` / `touches` / `crosses` / `disjoint` / `equals` — outros predicados DE-9IM
* `dwithin` / `beyond` — faixa de distância (`max_m` / `min_m`)
* `equals` / `ilike` — match por identificador contra subject register (set ancorado em um source `subject_register`)

Cada join é um mapping de chave única com o nome do operador. Combine
joins via blocos `all` / `any` / `not` dentro de `joins[]`.

Você também pode construir sets via operações de conjunto:

```json theme={null}
{
  "any_protected": {
    "from_set_op": {
      "op": "union",
      "operands": ["$indigenous_overlap", "$conservation_overlap"]
    }
  }
}
```

### `projections` — o que computar

Projections produzem valores numéricos ou geométricos. Terminais
comuns:

* `count` — número de feições casadas
* `total_area_m2`, `total_perimeter_m`
* `overlap_ratio` — fração do input coberta
* `min_distance_m`, `max_distance_m`
* `aggregate` — sum / avg / min / max de uma propriedade da feição
* `merge` — geometria unificada (para visualização)

Projections **não** disparam o verdict — só produzem valores.

### `checks` — o que precisa valer

Checks têm uma **severity** e um **predicate**:

```json theme={null}
{
  "id": "max_3_overlaps",
  "severity": "medium",
  "predicate": {
    "type": "threshold",
    "projection": "total_overlap_count",
    "op": "<=",
    "value": 3
  }
}
```

Severities, da mais forte para a mais fraca: `critical`, `high`,
`medium`, `low`, `info`. Veja [Verdicts](/pt-BR/concepts/verdicts)
para entender como mapeiam para outcomes.

## Atalho inline

Caso comum — count + threshold em um único check. O parser aceita:

```json theme={null}
{
  "id": "at_least_one_car",
  "severity": "high",
  "predicate": {
    "type": "count",
    "set": "$car_overlap",
    "op": ">=",
    "value": 1
  }
}
```

A projection do threshold fica implícita pelo predicate.

## Filtros

Restrinja um set com `filter`:

```json theme={null}
{
  "recent_embargoes": {
    "source": "ibama_embargos",
    "joins": [{ "intersects": { "target": "$input" } }],
    "filter": {
      "within_days": { "prop": "embargo_date", "value": 365 }
    }
  }
}
```

## Política de verdict customizada

Sobrescreva o mapeamento default de severity com uma política
explícita:

```json theme={null}
{
  "verdict_policy": {
    "kind": "severity_mapping",
    "rules": {
      "critical": "non_compliant",
      "high":     "non_compliant",
      "medium":   "warning",
      "low":      "warning",
      "info":     "compliant"
    }
  }
}
```

## Limites

Para manter respostas previsíveis, a API impõe:

| Limite                       | Default   |
| ---------------------------- | --------- |
| Máximo de sets               | 20        |
| Máximo de checks             | 50        |
| Máximo de projections        | 20        |
| Profundidade máxima          | 5         |
| Distância máxima de buffer   | 50 km     |
| Área máxima do input         | 1 000 km² |
| Máximo de evidence por check | 20        |

Exceder qualquer um retorna `422 PROGRAM_VALIDATION_ERROR`.

## A seguir

* [Exemplos](/pt-BR/authoring/examples) — rulesets completos para
  políticas comuns.
* [Catálogo](/pt-BR/authoring/catalog) — salve e versione seu
  ruleset.