#scrambledrop: Scramble 0.13.21

April 26, 2026

Laravel's new JSON:API resources support, `toResource` and `toResourceCollection` support, stricter types for Laravel Query Builder documentation.

Laravel’s JSON:API support

Scramble previously supported JSON:API via the timacdonald/json-api package in PRO.

Laravel now provides native JSON:API resources, and Scramble supports them out of the box in the open-source version!

Scramble documents not only the resource schema, but also the query parameters introduced by JSON:API resources. This includes include and fields[*], allowing clients to include relationships and select specific fields. Resource features like toLinks, toMeta, and JsonApiResource::configure are supported as well.

1
use App\Http\Resources\AppointmentResource;
2
use App\Models\Appointment;
3
use Illuminate\Support\Facades\Route;
4

5
Route::get('/appointments', function () {
6
    return AppointmentResource::collection(Appointment::paginate());
7
});

1
use Illuminate\Http\Request;
2
use Illuminate\Http\Resources\JsonApi\JsonApiResource;
3

4
class AppointmentResource extends JsonApiResource
5
{
6
    public $attributes = [
7
        'title',
8
        'description',
9
        'status',
10
        'created_at',
11
    ];
12

13
    public $relationships = [
14
        'bookedBy' => UserResource::class,
15
        'invoices',
16
    ];
17

18
    public function toLinks(Request $request): array
19
    {
20
        return [
21
            /**
22
             * Self link is the way to go.
23
             */
24
            'self' => route('scramble.docs.ui'),
25
        ];
26
    }
27

28
    public function toMeta(Request $request): array
29
    {
30
        return [
31
            'readable_created_at' => $this->created_at->diffForHumans(),
32
        ];
33
    }
34
}

1
use Illuminate\Http\Resources\JsonApi\JsonApiResource;
2

3
class UserResource extends JsonApiResource
4
{
5
    public $attributes = [
6
        'name',
7
        'email',
8
        'created_at',
9
    ];
10
}

1
use Illuminate\Http\Resources\JsonApi\JsonApiResource;
2

3
class InvoiceResource extends JsonApiResource
4
{
5
    public $attributes = [
6
        'number',
7
        'amount_cents',
8
        'currency',
9
        'status',
10
        'created_at',
11
    ];
12
}

Learn more about JSON:API support.

toResource and toResourceCollection support

toResource and toResourceCollection methods can be used on models, model collections, and paginators. They resolve the appropriate resource using Laravel’s conventions, and are widely used in official examples.

Scramble now supports these methods. It correctly infers the underlying resource not only for single models, but also for collections and paginators.

This required improvements in type inference, which now allows Scramble to follow these calls and produce accurate response schemas.

1
use App\Http\Controllers\Controller;
2
use App\Models\Project;
3

4
class ProjectController extends Controller
5
{
6
    public function index()
7
    {
8
        return Project::query()
9
            ->latest()
10
            ->paginate()
11
            ->toResourceCollection();
12
    }
13

14
    public function show(Project $project)
15
    {
16
        return $project->toResource();
17
    }
18
}

1
use Illuminate\Http\Request;
2
use Illuminate\Http\Resources\Json\JsonResource;
3

4
class ProjectResource extends JsonResource
5
{
6
    public function toArray(Request $request): array
7
    {
8
        return [
9
            'title' => $this->title,
10
            'description' => $this->description,
11
            'is_active' => $this->is_active,
12
            'created_at' => $this->created_at,
13
        ];
14
    }
15
}

Laravel Query Builder support improvements: native JSON:API compatibility, strict parameter types

Laravel Query Builder support received focused improvements in this release.

Scramble now correctly resolves precedence between native JSON:API parameters and spatie/laravel-query-builder parameters. When Laravel Query Builder is used, its configuration (allowedIncludes, allowedFields) takes priority and defines the actual set of allowed values. Parameters like include and fields[*] are derived from this configuration, so only valid values are documented.

Parameter handling is aligned with JSON:API serialization rules and expressed using proper OpenAPI schema. Instead of documenting parameters like include as string with described values, they are now defined as arrays with enumerated items. With explode: false, these arrays are serialized as comma-separated values (e.g. include=foo,bar) while remaining arrays in the schema.

1
{
2
    "name": "fields[appointments]",
3
    "in": "query",
4
    "schema": {
5
        "type": "array",
6
        "items": {
7
            "type": "string",
8
            "enum": [
9
                "title",
10
                "description",
11
                "status",
12
                "created_at"
13
            ]
14
        }
15
    },
16
    "explode": false
17
}

Fallback to previous behavior is available via configuration. If you prefer the old approach where JSON:API array parameters are documented as string, you can switch the serialization strategy:

1
use Dedoc\Scramble\Scramble;
2
use Dedoc\Scramble\Enums\JsonApiArraySerialization;
3

4
Scramble::configure()
5
    ->jsonApi(
6
        arraySerialization: JsonApiArraySerialization::String,
7
    );

This keeps parameters like include as string in the schema and moves allowed values back into the description, matching the previous behavior.

This release intentionally changes generated OpenAPI schema shape (mainly from string to array for JSON:API-style query parameters). Therefore, it may change the behavior of client generated from the OpenAPI schema, so it is released as Scramble PRO 0.9.0, and requires an explicit upgrade.

Other notable changes

Scramble PRO (Laravel Query Builder)

• Improved type inference for query builder instances: Scramble now infers the model type for the query builder generic, so expressions like QueryBuilder::from(SomeModel::class)->get()->toResourceCollection() are documented correctly.
• When allowedFields is used, Scramble documents the parameter as fields[${model table name here}] (for example, fields[appointments]) instead of plain fields, aligning better with the JSON:API specification.
• Improved include documentation for AllowedInclude::relationship(...) in Laravel Query Builder 7.0+: redundant values like postsCount and postsExists are no longer documented when only posts should be available.

Scramble

• Add attributes support on FormRequest (e.g. #[*Parameter], #[SchemaName])
• Improved type templates inference
• Improve type inference so when (from Conditional trait) is supported
• Soft delete methods support
• Fix #[SchemaName] attribute not reflected in response description by @dbrekelmans
• Fix required rule on arrays not setting minItems: 1 by @dbrekelmans
• Fix enum placed on array instead of items in OpenAPI spec by @dbrekelmans