Skip to content
VB-OSVB-OSVB-OS Docs

VB-OS Evidence Mapping Configuration

Mapping Structure

Section titled “Mapping Structure”

Each evidence mapping connects a source field from the provider to a target field in the boundary:

connector = client.connectors.create(
    project_id="PROJECT_ID",
    provider="stripe",
    name="Stripe Payments",
    credentials={"api_key": "sk_..."},
    evidence_mappings=[
        {
            "evidence_field": "payout_terminal_status",
            "source_path": "data.status",
            "transform": "categorical_map",
            "transform_config": {
                "mapping": {"succeeded": 1, "failed": 0, "pending": 0}
            },
        },
        {
            "evidence_field": "amount",
            "source_path": "data.amount",
            "transform": "to_integer",
        },
    ],
)

Fields

Section titled “Fields”
Field Description
evidence_field Target field name in the boundary
source_path Dot-notation path into the provider response
transform Optional transformation function
transform_config Configuration for the transform

Transforms

Section titled “Transforms”

identity

Section titled “identity”

Pass the value through unchanged. This is the default when no transform is specified.

to_integer

Section titled “to_integer”

Convert the value to an integer. Useful because VBL is integer-only: all comparisons use 64-bit signed integers.

to_string

Section titled “to_string”

Convert the value to a string.

to_boolean

Section titled “to_boolean”

Convert the value to a boolean.

categorical_map

Section titled “categorical_map”

Map string categories to integer values using a lookup table. This is essential for VBL’s integer-only evaluation engine:

{
    "evidence_field": "payout_terminal_status",
    "source_path": "data.status",
    "transform": "categorical_map",
    "transform_config": {
        "mapping": {
            "succeeded": 1,
            "failed": 0,
            "pending": 0,
            "canceled": 0,
        }
    },
}

Fail-closed behavior: If the source value does not match any key in the mapping, the gather fails. No evidence is produced, and the evaluation (if auto-evaluate is enabled) receives incomplete evidence, resulting in DEFER. This prevents unmapped categories from silently passing through.

to_timestamp

Section titled “to_timestamp”

Convert a date or datetime value to a Unix timestamp (integer seconds since epoch).

jsonpath

Section titled “jsonpath”

Extract a value using a JSONPath expression.

json_parse

Section titled “json_parse”

Parse a JSON string into a structured value.

Source Path

Section titled “Source Path”

The source_path uses dot notation to navigate nested provider responses:

  • data.status: access status inside data
  • data.amount: access amount inside data
  • metadata.customer_id: access nested metadata fields

Next Steps

Section titled “Next Steps”