SchemaStack

Appearance

Field Selection ​

Use the fields query parameter to control which fields are included in the response. This reduces payload size and lets you fetch only the data you need.

Default Behavior ​

Without fields, all columns are returned:

http
GET /api/v1/acme-corp/sales/Customer/42
json
{
  "data": {
    "id": 42,
    "name": "Jane Doe",
    "email": "[email protected]",
    "phone": "+1-555-0123",
    "company": "Acme Corp",
    "notes": "VIP customer since 2024..."
  }
}

Selecting Fields ​

Specify a comma-separated list of field names:

http
GET /api/v1/acme-corp/sales/Customer/42?fields=id,name,email
json
{
  "data": {
    "id": 42,
    "name": "Jane Doe",
    "email": "[email protected]"
  }
}

Fields not in the list are omitted from the response.

Nested Field Selection ​

When combined with expand, you can select specific fields on the expanded relationship using dot notation:

http
GET /api/v1/acme-corp/sales/Order?expand=customer&fields=id,total,customer.name
json
{
  "data": [
    {
      "id": 1,
      "total": 150.0,
      "customer": {
        "name": "Jane Doe"
      }
    }
  ],
  "meta": { "page": 0, "size": 20, "totalElements": 1, "totalPages": 1 }
}

Note how customer.name includes only the name field from the expanded customer, and top-level fields like orderNumber are excluded because they weren't listed.

Expanding Without Filtering ​

If you include a relationship name without dot notation, all of its fields are returned:

http
GET /api/v1/acme-corp/sales/Order?expand=customer&fields=id,customer
json
{
  "data": [
    {
      "id": 1,
      "customer": {
        "id": 42,
        "name": "Jane Doe",
        "email": "[email protected]"
      }
    }
  ]
}

Works on All Read Endpoints ​

The fields parameter works on both list and single-record endpoints:

GET /api/v1/{org}/{workspace}/{entity}?fields=id,name              # list
GET /api/v1/{org}/{workspace}/{entity}/{id}?fields=id,name         # single record

Admin Configuration ​

Workspace administrators can set a default field selection per entity. When configured, responses only include the specified fields by default, even when no ?fields parameter is provided.

An explicit ?fields= parameter always overrides the default.

Combining with Other Parameters ​

Field selection works alongside all other query parameters:

http
GET /api/v1/acme-corp/sales/Order?fields=id,total,customer.name&expand=customer&sort=total,desc&page=0&size=10

SchemaStack Documentation