Metadata Mapping

Beetles allows you to attach arbitrary JSON metadata to almost any resource (Transfers, Identities, accounts). While this flexibility is powerful, it can make it difficult to enforce business logic or build complex queries.

Metadata Mapping (also known as Rules Fields) solves this by allowing you to define a "schema" for your metadata at the workspace level.

Why use Metadata Mapping?

1. Type Safety: Ensure a field like risk_score is always treated as a number, even if it's passed as a string in the JSON.
2. Dot-Notation Access: Map nested JSON paths (e.g., analysis.fraud.score) to a simple flat key (fraud_score).
3. Engine Integration: The Rules Engine uses these mappings to evaluate conditions efficiently.
4. Discoverability: Registered fields appear in the Dashboard UI, making it easier for non-technical users to build rules.

Registering a Field

A metadata field definition consists of:

• Label: A human-readable name (e.g., "Merchant Category").
• Key: The identifier used in rules and queries (e.g., mcc).
• Path: The dot-notation path to the value in the metadata JSON (e.g., merchant.mcc).
• Data Type: The expected type of the value (string, numeric, decimal, boolean).

Example

Suppose you send transfers with this metadata:

{
  "context": {
    "ip_address": "1.2.3.4",
    "risk": {
      "level": "high",
      "score": 85
    }
  }
}

You can register a mapping for the risk score:

• Label: Risk Score
• Key: risk_score
• Path: context.risk.score
• Data Type: numeric

Now, you can create a rule that references metadata.risk_score directly.

System Default Fields

When you create a new workspace, Beetles automatically seeds a set of standard metadata fields:

You can modify or delete these mappings at any time to match your application's metadata structure.

Integration with Rules

The Rules Engine uses these mappings to extract and cast values during evaluation. For example, if you have a field mapped as numeric, the engine will automatically convert string values (e.g., "100") to numbers before performing comparisons like > or <.

Next, learn how to use these fields in Rules and Watchers.