SaaS APIs have been getting more “JSON-shaped” every year. The early days were simple: a record was mostly flat, and integrating meant translating firstname to first_name and calling it a day.

Today, the real data often lives one or two (or five) levels down: user.profile.email, properties.custom_fields.priority, metadata.owner.id, and so on. And the moment you want a reliable, real-time, two-way sync (read/subscribe and write), the glue code starts to sprawl: custom parsers, edge-case handling for weird field names, one-off transforms for each provider, and endless “why didn’t this update?” debugging.

📢📢 That’s why today we’re launching nested field mappings in Ampersand. We want to ensure enterprise agent builders can build deep integrations where nested data from Systems of Record is table stakes.

What’s new: Nested field mappings (read + write) using JSONPath bracket notation

Ampersand now supports mapping to and from nested fields using JSONPath bracket notation, so you can work with nested data structures when reading from provider APIs and writing back. Docs are here.

Use this format to access nested values:

$['parentField']['childField']

Bracket notation is also the safest way to reference field names that contain special characters like dots or spaces (which show up constantly in real-world SaaS schemas).

And importantly: this works both directions.

• Reading: extract nested provider values into mapped fields
• Writing: reverse the same mapping when sending data back to the provider

Why bracket notation (and not just dots)?

Dot notation breaks down fast in the real world:

• Some providers embed dots in field names
• Custom fields can include spaces, punctuation, or provider-specific prefixes
• You end up writing fragile escaping logic

Ampersand’s nested mapping support uses bracket notation, so those field names are parsed correctly and consistently.

A concrete example: Read nested data, deliver clean mapped fields

Say a provider returns this payload:

{
  "userInfo": {
    "email": "john@example.com",
    "name": "John Doe"
  },
  "status": "active"
}

You can define field mappings like:

read:
  objects:
    - objectName: contacts
      requiredFields:
        - mapToName: contactEmail
          fieldName: $['userInfo']['email']
        - mapToName: contactName
          fieldName: $['userInfo']['name']

Ampersand delivers the normalized output under mappedFields:

{
  "mappedFields": {
    "contactEmail": "john@example.com",
    "contactName": "John Doe"
  }
}

This “provider shape in, product shape out” behavior is exactly what mappings are for, and nested mappings make it work when the provider isn’t flat.

The best part: the same mapping applies in reverse when you write

When you write back, Ampersand applies the same mapping in reverse, so your app can keep speaking in the stable schema you chose, while the provider receives the schema it expects. Ampersand+1

Using the docs’ nested read/write mapping example, notice something subtle and powerful: you can also use bracket notation on the destination side (your mapToName) to produce nested output structures.

- mapToName: $['moreInfo']['currentStatus']
  fieldName: status

Now your app can send:

{
  "moreInfo": { "currentStatus": "deleted" }
}

…and the provider receives:

{
  "status": "deleted"
}

Meanwhile nested provider fields like userInfo.email and userInfo.name map back into userInfo on the provider side during writes.

Object + field mapping: the integration primitive that scales

Nested field mappings are the newest capability, but they sit on top of a broader (and increasingly essential) foundation: object mapping and field mapping.

Ampersand supports both, and you can either:

• Predefine mappings in your manifest (amp.yaml)
• Or prompt end users to define mappings via Ampersand UI components (for custom fields, org-by-org differences, etc.)

Object mapping

Object mapping lets you rename provider objects into your own vocabulary—useful for enforcing conventions, or building a unified API across multiple providers.

Example: map Salesforce account and HubSpot companies into your product’s canonical company. Ampersand delivers results under the mapped object name while still preserving the provider’s original name as rawObjectName.

Field mapping

Field mapping does the same at the field level—standardizing keys and insulating your app from provider-specific naming.

And because Ampersand can apply the mapping in reverse for writes (when you inherit mappings), mapping becomes more than a “read transform”—it becomes a two-way contract.

User-defined mappings (for custom fields)

Customers don’t all use the same CRM schema. One org stores “notes” in field_a, another uses field_b. User-defined field mappings let you ask each customer to map their field into your concept, once, at install time—then you always receive it under the same canonical name.

Ampersand currently supports user-defined field mappings (not object mappings yet). Please let us know if you need this feature and the business use cases that you want them for!

Dynamic field mappings

Sometimes the set of fields to map isn’t even fixed—you may need to generate it per customer, per workflow, or per product tier.

Ampersand supports dynamic field mappings by passing a fieldMapping configuration into the InstallIntegration UI component, and these dynamic mappings are optional (users can install without mapping).

Value mappings (including bracket notation support)

Mappings aren’t only about field names. They’re also about value vocabularies—especially for enums like lifecycle stage, priority, lead source, etc.

Ampersand supports value mappings (one-to-one), configured through the UI flow. And value mappings support bracket notation as well—so nested keys don’t block you from mapping nested data cleanly.

Why mappings matter even more in the age of AI: determinism + authorization

AI is changing how integrations get built and operated. Teams are moving from “a developer writes a transformation” to:

• agents generating connector code,
• LLMs proposing field mappings from schema introspection,
• copilots drafting sync logic,
• autonomous workflows taking actions on customer systems.

That’s exciting, and also exactly where integration complexity becomes dangerous.

Determinism: a stable contract that the model can’t “creatively reinterpret”

LLMs are probabilistic. Your integration shouldn’t be.

Object and field mapping is the deterministic layer that turns “best effort schema guessing” into “this is the contract.” Once a mapping is set:

• Reads always land in the same canonical shape (mappedFields)
• Writes always reverse the same mapping back to provider fields

Nested mappings extend that determinism to the parts of the payload that previously required bespoke parsing code. No more “sometimes it’s user.email, sometimes it’s userInfo.email” scattered through your app, your app talks to your schema, and Ampersand handles the rest.

Authorization: mappings define what data is allowed to move

In modern integrations, authorization isn’t only “can we connect?” It’s also:

• Which objects are we allowed to sync?
• Which fields are we allowed to read?
• Which fields are we allowed to write back?
• What happens if a customer doesn’t have (or doesn’t want to map) a field?

Ampersand’s read configuration distinguishes required vs optional fields, where required means every installing user must grant access, and optional means the user can choose whether to grant access.

On the write side, inheritance and mapping rules give you a clean, enforceable boundary: you write in terms of your canonical mapped fields, and Ampersand routes that to the correct provider fields—or strips fields that weren’t mapped to prevent provider errors (and, practically speaking, to prevent accidental writes into undefined/unapproved fields).

In an AI-driven world where actions can be suggested (or even taken) automatically, that boundary becomes the difference between:

• a controlled system that can be audited and reasoned about,
• and a fuzzy system where the model’s guess becomes production behavior.

Nested objects: the reality of SaaS data

Nested data shows up everywhere:

• “properties” objects wrapping actual values
• “metadata” wrappers with IDs and provenance
• field groups like userInfo, billingAddress, owner, attributes
• special-character field names that are hard to address reliably

Nested field mappings let you:

• pull values out of provider nesting using $['a']['b']
• write values back into provider nesting using the same mapping reversed
• emit nested output on your side by using bracket notation in mapToName

This is a big step toward integrations that preserve structure instead of flattening everything into an ad hoc key soup.

The association graph: integrations aren’t tables, they’re relationships

Even if every record were flat, integrations still wouldn’t be.

A CRM isn’t “a list of contacts.” It’s a graph:

• contacts associated with companies
• deals associated with contacts and companies
• tickets associated with contacts
• activities associated with deals
• custom objects linked across multiple entity types

If you want your product to behave like a first-class citizen in your customer’s system, you have to model, and sync, those relationships. That’s the association graph: nodes are records, edges are associations, and your integration’s job is to keep those edges accurate over time.

Ampersand exposes a couple of key primitives that map naturally onto this:

Writing edges: create associations at write time (HubSpot)

When creating records via the Write API, you can include an associations parameter to create linked records, currently supported for HubSpot.

That’s not just convenience. It’s the difference between:

1. create record, then
2. do extra calls to connect it, then
3. reconcile failures…

…versus treating “create node + connect edge” as a single declarative intent.

Reacting to edge changes: association update events (HubSpot subscribe)

On the eventing side, Ampersand’s subscribe webhooks include a normalized subscribeEventType that can be create, update, delete, and associationUpdate (HubSpot only)—so you can react when relationships change, not just when fields change.

Where nested field mappings fit

Associations are often represented as nested structures in API payloads (or at least nested metadata pointing to IDs). Nested field mappings let you reliably access and emit those nested relationship signals without writing custom traversal logic for each provider.

Put differently:

• Nested mappings let you address structure inside a node
• Association primitives/events let you model edges between nodes
• Together, they make the “graph” first-class in your integration architecture

Summary

Nested field mappings are a deceptively small feature with an outsized impact:

• They remove a major source of custom glue code for nested provider payloads
• They make your “canonical schema” truly end-to-end (read + write)
• They increase determinism in a world where AI systems are otherwise probabilistic
• They strengthen authorization boundaries by keeping data movement explicit and controlled
• They complement the association graph view of integrations, because real systems are networks, not tables

For the full technical details and examples, see Ampersand’s Object and field mapping documentation.

We cannot wait to see what you build with it.