YAML & JSON Schemas

Describe your whole API in one declarative, versionable file: commit it, review it in PRs, regenerate at will.

YAML schema

Create api-schema.yaml at the project root:

options:
  query_builder: true
  pest: true

entities:
  Category:
    fields:
      name: string unique
    relations:
      posts: hasMany Post

  Post:
    soft_deletes: true
    fields:
      title: string
      content: text nullable
      status: enum(draft,published) default=draft
      views: { type: integer, default: 0 }
    relations:
      tags: belongsToMany Tag

  Tag:
    fields:
      name: string unique

php artisan make:fullapi --schema=api-schema.yaml

When api-schema.yaml (or .yml / .json) exists at the project root, you can even drop the flag: a bare php artisan make:fullapi picks it up automatically.

Field syntax

Fields accept a shorthand (title: string) or a full mapping when you need extra keys like rules:

fields:
  title: string
  slug: string unique
  excerpt: text nullable
  code: string primary
  status: enum(draft,published) default=draft
  views: { type: integer, default: 0, rules: 'min:0' }

unique, nullable and default= decorate the shorthand, and primary promotes the field to custom primary key.

Options

Options can be global (under options:) or per entity:

Option	Effect
soft_deletes: true	SoftDeletes trait + restore/force-delete endpoints
query_builder: true	Spatie QueryBuilder filtering & sorting on index
pest: true	Pest tests instead of PHPUnit
json_api: true	JSON:API resources (Laravel 12.45+, standard resources on older versions)

Editor autocompletion

The package ships a JSON Schema of this format. Point the first line of the file at it, and any editor running the YAML language server completes keys and types, and flags typos such as strng or nulable before you generate:

# yaml-language-server: $schema=https://nameless0l.github.io/laravel-api-generator/schema/api-schema.json

The VS Code extension applies the schema to api-schema.yaml, api-schema.yml and api-schema.json on its own. Offline, the same file sits in vendor/nameless/laravel-api-generator/resources/schema/api-schema.json.

Outside the editor, make:fullapi still generates a field of unknown type as a string column, and reports it with an unknown_field_type warning that names the field.

What you get for free

• Inverse relations synthesized: declare posts: hasMany Post on Category, and Post receives the belongsTo and its category_id migration column. Details.
• Foreign-key-safe ordering: entities are generated parents-first so php artisan migrate never trips on a missing table.
• Automatic pivots: every belongsToMany creates its pivot migration.

JSON bulk mode (class_data.json)

The original bulk format, still fully supported: create class_data.json at the project root and run php artisan make:fullapi with no arguments. See Relationships → JSON mode for the format, or download the sample Blog schema.

AI-friendly

A single YAML file describing a whole API is an ideal target for AI assistants: ask your favorite model for a schema, review it, generate. The assistant cannot hallucinate file paths, since the generator decides the layout. With Laravel Boost, the agent learns the format from the package's skill: see Tools & Agents.