Skip to main content
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

{
  "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: 
{
  "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: 
{
  "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 for how they map to outcomes.

​
Inline shorthand

Common case — count + threshold in a single check. The parser accepts: 
{
  "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: 
{
  "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: 
{
  "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:
LimitDefault
Max sets20
Max checks50
Max projections20
Max nesting depth5
Max buffer distance50 km
Max input area1 000 km²
Max evidence per check20
Exceeding any of them returns 422 PROGRAM_VALIDATION_ERROR.

​
Next

  • Examples — full rulesets for common policies.
  • Catalog — save and version your ruleset.