# Field Mapping

Field mapping is how you tell Weavestream which parts of an API response correspond to the title, summary, date, status, and ID of each item. Good field mapping makes your data easy to browse and search.

When you fetch sample data during endpoint setup, Weavestream analyzes the JSON response and discovers all available fields. These fields appear as dropdown options in the mapping step.

Weavestream automatically looks for common field names and suggests them:

If your API uses different field names, you can select any discovered field from the dropdown.

Many APIs return nested JSON objects. Weavestream uses dot notation to access nested fields. For example, given this response:

{
  "id": 123,
  "metadata": {
    "severity": "high",
    "created": "2025-01-15T10:30:00Z"
  },
  "user": {
    "profile": {
      "name": "Jane Smith"
    }
  }
}

You could map:

• Status → metadata.severity
• Date → metadata.created
• Title → user.profile.name

Weavestream discovers nested fields automatically when you fetch sample data, so they'll appear in the field dropdowns with their full dot-notation path.

Some APIs wrap their items inside a nested object rather than returning a top-level array. The Array Path tells Weavestream where to find the list of items.

Top-level array (no Array Path needed):

[
  { "id": 1, "title": "Item One" },
  { "id": 2, "title": "Item Two" }
]

Nested array (set Array Path to data.items):

{
  "status": "success",
  "count": 2,
  "data": {
    "items": [
      { "id": 1, "title": "Item One" },
      { "id": 2, "title": "Item Two" }
    ]
  }
}

Common Array Paths:

• data — Many APIs wrap results in a data field
• data.items — Nested inside a data object
• results — Common in paginated APIs
• response.records — Some enterprise APIs use this pattern

Rather than mapping a single field for title and summary, Weavestream lets you specify a fallback chain — an ordered list of fields to try. It uses the first field that has a non-empty value for each item.

This is especially useful when:

• Different items in the same endpoint store their title in different fields
• Some items might have a title field while others use name or subject
• You want a composite view where the most descriptive field wins

Example fallback chain for titles:

1. title — Try this first
2. name — Fall back to this
3. subject — Last resort

Click Add Title Field or Add Summary Field in the mapping step to add more levels to the chain.

The status field maps to colored badges that appear on each item:

If your status field is a boolean (e.g., isResolved, hasError), Weavestream maps true to OK and false to Critical by default. Toggle Invert boolean value if you need the opposite behavior (e.g., true on hasError should be Critical).

• Always set the ID field — This is how Weavestream tracks items across syncs. Without a unique ID, items may duplicate.
• Set a Date field — This enables sorting by Newest/Oldest and shows timestamps in the item list.
• Use fallback chains — They make your items more readable when field names vary.
• Check the live preview — The right panel in the mapping step updates in real time. If items look wrong, adjust your mapping.

• Configuring Endpoints — Full endpoint setup guide
• Pagination — Fetch all pages of data
• Smart Filters — Filter items by field values