What is JSONPath Mapping?
JSONPath mapping is the technique of using JSONPath expressions to extract specific fields from upstream API responses and map them to capability output parameters. It is the primary mechanism for response shaping and context right-sizing in Naftiko capabilities.
How it works
JSONPath expressions navigate JSON document structures using dot notation and bracket syntax. In a capability spec, each output parameter includes a mapping expression that tells the framework which field to extract from the upstream response.
For example, $.data.users[*].email extracts all email addresses from a nested response structure, while $.metadata.total_count extracts a single value.
Cross-source mapping
In multi-step capabilities, JSONPath mapping also bridges data between steps. Output from one step can be mapped as input to the next, enabling cross-source orchestration without custom code.
Why it matters
JSONPath mapping decouples the capability’s contract from the upstream API’s response structure. Upstream APIs can change their response format, and the capability only needs to update its mapping expressions – not its consumer-facing contract. This insulation protects consumers from upstream volatility.
