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

{
  "name": "br-rural-credit",
  "version": 1,
  "description": "Rural credit eligibility per Resolução BCB 4.943",

  "sets": {
    "indigenous_overlap": {
      "source": "br:funai:indigenous-territories",
      "join": { "op": "intersects", "target": "$input" }
    },
    "embargo_overlap": {
      "source": "br:ibama:embargoed-areas",
      "join": { "op": "intersects", "target": "$input" }
    }
  },

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

  "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
• dwithin — within a buffer distance
• disjoint — no overlap
• subject_match — match by identifier (for subject registers)

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": "br:ibama:embargoed-areas",
    "join": { "op": "intersects", "target": "$input" },
    "filter": {
      "type": "temporal_relative",
      "property": "embargo_date",
      "op": "within_days",
      "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:

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 — full rulesets for common policies.
• Catalog — save and version your ruleset.