Sparse Fieldsets

Sparse Fieldsets

Request only the fields you need

---

Overview

Sparse fieldsets allow clients to request a subset of attributes for each resource type. This reduces payload size and improves performance by excluding unnecessary data.

---

Fields Object

The fields object specifies which attributes to include per resource type:

{
  "fields": {
    "self": ["id", "status", "total_amount", "created_at"],
    "customer": ["id", "name"]
  }
}

Structure

Key	Description
self	Fields for the primary resource
<relationship>	Fields for related resources

Rules

• Keys are resource type identifiers
• Values are arrays of attribute names
• id and type are always included (not specified in fieldset)
• Empty array [] returns only type and id
• Absent key returns all fields for that type

---

Request Format

{
  "protocol": { "name": "mesh", "version": "0.1.0" },
  "id": "req_123",
  "call": {
    "function": "orders.get",
    "version": "1",
    "arguments": {
      "id": "12345",
      "fields": {
        "self": ["id", "status", "total_amount"],
        "customer": ["id", "name", "email"]
      },
      "relationships": ["customer"]
    }
  }
}

---

Response Format

Response includes only requested fields:

{
  "protocol": { "name": "mesh", "version": "0.1.0" },
  "id": "req_123",
  "result": {
    "data": {
      "type": "order",
      "id": "12345",
      "attributes": {
        "status": "pending",
        "total_amount": { "amount": "99.99", "currency": "USD" }
      },
      "relationships": {
        "customer": {
          "data": { "type": "customer", "id": "42" }
        }
      }
    },
    "included": [
      {
        "type": "customer",
        "id": "42",
        "attributes": {
          "name": "Alice",
          "email": "alice@example.com"
        }
      }
    ]
  }
}

Note: type and id are always present even when not in the fieldset.

---

Allowed Fields

Servers MUST define which fields are queryable per resource:

{
  "fields": {
    "self": ["id", "order_number", "status", "total_amount", "created_at", "updated_at"],
    "customer": ["id", "name", "email", "type"],
    "items": ["id", "sku", "name", "quantity", "price"]
  }
}

Validation

• Requesting non-allowed fields MUST return an error
• Servers SHOULD expose allowed fields via mesh.describe

Error Response

{
  "errors": [{
    "code": "INVALID_ARGUMENTS",
    "message": "Field not allowed: secret_notes",
    "retryable": false,
    "source": {
      "pointer": "/call/arguments/fields/self/3"
    },
    "details": {
      "field": "secret_notes",
      "resource": "self",
      "allowed": ["id", "order_number", "status", "total_amount", "created_at", "updated_at"]
    }
  }]
}

---

Default Behavior

No Fields Specified

When fields is absent, servers return all allowed fields:

// Request without fields
{
  "arguments": {
    "id": "12345"
  }
}

// Response includes all fields
{
  "data": {
    "type": "order",
    "id": "12345",
    "attributes": {
      "order_number": "ORD-2024-001",
      "status": "pending",
      "total_amount": { "amount": "99.99", "currency": "USD" },
      "item_count": 3,
      "notes": null,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:35:00Z"
    }
  }
}

Empty Fieldset

Empty array returns only type and id:

// Request
{
  "fields": {
    "self": []
  }
}

// Response
{
  "data": {
    "type": "order",
    "id": "12345"
  }
}

Relationship Not in Fields

When a relationship is requested but not in fields, include only identifiers:

// Request
{
  "fields": {
    "self": ["id", "status"]
  },
  "relationships": ["customer"]
}

// Response - customer has no fields specified, so all allowed fields returned
{
  "data": {
    "type": "order",
    "id": "12345",
    "attributes": {
      "status": "pending"
    },
    "relationships": {
      "customer": {
        "data": { "type": "customer", "id": "42" }
      }
    }
  },
  "included": [
    {
      "type": "customer",
      "id": "42",
      "attributes": {
        "name": "Alice",
        "email": "alice@example.com",
        "type": "premium"
      }
    }
  ]
}

---

Field Selection Patterns

Minimal Response

Request only identifiers:

{
  "fields": {
    "self": []
  }
}

Summary View

Request key fields for list views:

{
  "fields": {
    "self": ["id", "status", "total_amount", "created_at"]
  }
}

Detail View

Request all fields including relationships:

{
  "fields": {
    "self": ["id", "order_number", "status", "total_amount", "notes", "created_at", "updated_at"],
    "customer": ["id", "name", "email"],
    "items": ["id", "sku", "name", "quantity", "price"]
  },
  "relationships": ["customer", "items"]
}

Specific Use Case

Request only what’s needed:

// For a shipping label
{
  "fields": {
    "self": ["id", "order_number"],
    "shipping_address": ["id", "line1", "line2", "city", "postal_code", "country_code"],
    "customer": ["id", "name", "phone"]
  },
  "relationships": ["shipping_address", "customer"]
}

---

Examples

Single Resource

// Request
{
  "protocol": { "name": "mesh", "version": "0.1.0" },
  "id": "req_single",
  "call": {
    "function": "customers.get",
    "version": "1",
    "arguments": {
      "id": "42",
      "fields": {
        "self": ["id", "name", "email", "created_at"]
      }
    }
  }
}

// Response
{
  "protocol": { "name": "mesh", "version": "0.1.0" },
  "id": "req_single",
  "result": {
    "data": {
      "type": "customer",
      "id": "42",
      "attributes": {
        "name": "Alice Smith",
        "email": "alice@example.com",
        "created_at": "2024-01-10T08:00:00Z"
      }
    }
  }
}

Collection with Sparse Fields

// Request
{
  "protocol": { "name": "mesh", "version": "0.1.0" },
  "id": "req_list",
  "call": {
    "function": "orders.list",
    "version": "1",
    "arguments": {
      "fields": {
        "self": ["id", "status", "total_amount"]
      },
      "pagination": {
        "limit": 10
      }
    }
  }
}

// Response
{
  "protocol": { "name": "mesh", "version": "0.1.0" },
  "id": "req_list",
  "result": {
    "data": [
      {
        "type": "order",
        "id": "12345",
        "attributes": {
          "status": "pending",
          "total_amount": { "amount": "99.99", "currency": "USD" }
        }
      },
      {
        "type": "order",
        "id": "12346",
        "attributes": {
          "status": "shipped",
          "total_amount": { "amount": "149.99", "currency": "USD" }
        }
      }
    ],
    "meta": {
      "page": {
        "cursor": {
          "current": "...",
          "next": "..."
        }
      }
    }
  }
}

With Related Resources

// Request
{
  "protocol": { "name": "mesh", "version": "0.1.0" },
  "id": "req_related",
  "call": {
    "function": "shipments.get",
    "version": "1",
    "arguments": {
      "id": "ship_123",
      "fields": {
        "self": ["id", "tracking_number", "status"],
        "origin": ["id", "name", "country_code"],
        "destination": ["id", "name", "postal_code", "country_code"],
        "events": ["id", "status", "occurred_at"]
      },
      "relationships": ["origin", "destination", "events"]
    }
  }
}

// Response
{
  "protocol": { "name": "mesh", "version": "0.1.0" },
  "id": "req_related",
  "result": {
    "data": {
      "type": "shipment",
      "id": "ship_123",
      "attributes": {
        "tracking_number": "MH726955185FI",
        "status": "in_transit"
      },
      "relationships": {
        "origin": {
          "data": { "type": "location", "id": "loc_001" }
        },
        "destination": {
          "data": { "type": "location", "id": "loc_002" }
        },
        "events": {
          "data": [
            { "type": "tracking_event", "id": "evt_001" },
            { "type": "tracking_event", "id": "evt_002" }
          ]
        }
      }
    },
    "included": [
      {
        "type": "location",
        "id": "loc_001",
        "attributes": {
          "name": "Helsinki Warehouse",
          "country_code": "FI"
        }
      },
      {
        "type": "location",
        "id": "loc_002",
        "attributes": {
          "name": "Tampere Office",
          "postal_code": "33100",
          "country_code": "FI"
        }
      },
      {
        "type": "tracking_event",
        "id": "evt_001",
        "attributes": {
          "status": "picked_up",
          "occurred_at": "2024-01-14T10:00:00Z"
        }
      },
      {
        "type": "tracking_event",
        "id": "evt_002",
        "attributes": {
          "status": "in_transit",
          "occurred_at": "2024-01-15T08:00:00Z"
        }
      }
    ]
  }
}

---

Discovery

Functions SHOULD advertise available fields via mesh.describe:

{
  "result": {
    "function": "orders.list",
    "query": {
      "fields": {
        "self": ["id", "order_number", "status", "total_amount", "item_count", "notes", "created_at", "updated_at"],
        "customer": ["id", "name", "email", "type", "country_code"],
        "items": ["id", "sku", "name", "quantity", "price", "total"]
      },
      "default_fields": {
        "self": ["id", "order_number", "status", "total_amount", "created_at"]
      }
    }
  }
}