> ## 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.

# Ruleset basics

> Encode your compliance policy as a JSON ruleset.

A **ruleset** is a JSON document that describes:

1. Which sources to query (and how to filter them).
2. What values to compute (counts, areas, distances).
3. What conditions must hold for the result to be compliant.

Send the ruleset inline on `/v1/evaluate`, or save it to the catalog
once and reference it by `name@version` afterwards.

## Anatomy

```json theme={null}
{
  "name": "br-rural-credit",
  "version": 1,
  "description": "Rural credit eligibility per 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" }
    }
  ]
}
```

## The three blocks

### `sets` — what features to consider

A set is anchored on a **source** and joined against `$input` (your
request geometry/identifier) or another set. Available join operators:

* `intersects` — geometry overlap
* `contains` / `within` — full containment
* `covers` / `covered_by` — containment including boundary touches
* `overlaps` / `touches` / `crosses` / `disjoint` / `equals` — other DE-9IM predicates
* `dwithin` / `beyond` — distance band (`max_m` / `min_m`)
* `equals` / `ilike` — identifier match against a subject register (set anchored on a `subject_register` source)

Each join is a single-key map keyed by the operator. Compose joins
with `all` / `any` / `not` blocks inside `joins[]`.

You can also build sets from set operations:

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

### `projections` — what to compute

Projections produce numeric or geometric values. Common terminals:

* `count` — number of matching features
* `total_area_m2`, `total_perimeter_m`
* `overlap_ratio` — fraction of input covered
* `min_distance_m`, `max_distance_m`
* `aggregate` — sum / avg / min / max of a feature property
* `merge` — unified geometry (for visualization)

Projections do **not** trigger the verdict — they only produce values.

### `checks` — what must hold

Checks have a **severity** and a **predicate**:

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

Severities, from strongest to weakest: `critical`, `high`, `medium`,
`low`, `info`. See [Verdicts](/concepts/verdicts) for how they map to
outcomes.

## Inline shorthand

Common case — count + threshold in a single check. The parser accepts:

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

The threshold projection is implied by the predicate.

## Filters

Restrict a set with `filter`:

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

## Custom verdict policy

Override the default severity mapping with an explicit policy:

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

## Limits

To keep responses predictable, the API enforces:

| Limit                  | Default   |
| ---------------------- | --------- |
| Max sets               | 20        |
| Max checks             | 50        |
| Max projections        | 20        |
| Max nesting depth      | 5         |
| Max buffer distance    | 50 km     |
| Max input area         | 1 000 km² |
| Max evidence per check | 20        |

Exceeding any of them returns `422 PROGRAM_VALIDATION_ERROR`.

## Next

* [Examples](/authoring/examples) — full rulesets for common policies.
* [Catalog](/authoring/catalog) — save and version your ruleset.