Validation

API Platform takes care of validating the data sent to the API by the client (usually user data entered through forms). By default, the framework relies on the powerful Symfony Validator Component for this task, but you can replace it with your preferred validation library such as the PHP filter extension if you want to.

Watch the Validation screencast

Validating Submitted Data

Validating submitted data is as simple as adding Symfony’s built-in constraints or custom constraints directly in classes marked with the @ApiResource annotation:

<?php
// api/src/Entity/Product.php

namespace App\Entity;

use ApiPlatform\Core\Annotation\ApiResource;
use App\Validator\Constraints\MinimalProperties; // A custom constraint
use Doctrine\ORM\Mapping as ORM;
use Symfony\Component\Validator\Constraints as Assert; // Symfony's built-in constraints

/**
 * A product.
 *
 * @ApiResource
 * @ORM\Entity
 */
class Product
{
    /**
     * @var int The id of this product.
     *
     * @ORM\Id
     * @ORM\GeneratedValue
     * @ORM\Column(type="integer")
     */
    private $id;

    /**
     * @var string The name of the product
     *
     * @Assert\NotBlank
     * @ORM\Column
     */
    public $name;

    /**
     * @var string[] Describe the product
     *
     * @MinimalProperties
     * @ORM\Column(type="json")
     */
    public $properties;

    // Getters and setters...
}

And here is the custom MinimalProperties constraint and the related validator:

<?php
// api/src/Validator/Constraints/MinimalProperties.php

namespace App\Validator\Constraints;

use Symfony\Component\Validator\Constraint;

/**
 * @Annotation
 */
class MinimalProperties extends Constraint
{
    public $message = 'The product must have the minimal properties required ("description", "price")';
}

<?php
// api/src/Validator/Constraints/MinimalPropertiesValidator.php

namespace App\Validator\Constraints;

use Symfony\Component\Validator\Constraint;
use Symfony\Component\Validator\ConstraintValidator;

/**
 * @Annotation
 */
final class MinimalPropertiesValidator extends ConstraintValidator
{
    public function validate($value, Constraint $constraint): void
    {
        if (!array_diff(['description', 'price'], $value)) {
            $this->context->buildViolation($constraint->message)->addViolation();
        }
    }
}

If the data submitted by the client is invalid, the HTTP status code will be set to 400 Bad Request and the response’s body will contain the list of violations serialized in a format compliant with the requested one. For instance, a validation error will look like the following if the requested format is JSON-LD (the default):

{
  "@context": "/contexts/ConstraintViolationList",
  "@type": "ConstraintViolationList",
  "hydra:title": "An error occurred",
  "hydra:description": "properties: The product must have the minimal properties required (\"description\", \"price\")",
  "violations": [
    {
      "propertyPath": "properties",
      "message": "The product must have the minimal properties required (\"description\", \"price\")"
    }
  ]
}

Take a look at the Errors Handling guide to learn how API Platform converts PHP exceptions like validation errors to HTTP errors.

Using Validation Groups

Without specific configuration, the default validation group is always used, but this behavior is customizable: the framework is able to leverage Symfony’s validation groups.

You can configure the groups you want to use when the validation occurs directly through the ApiResource annotation:

<?php
// api/src/Entity/Book.php

use ApiPlatform\Core\Annotation\ApiResource;
use Symfony\Component\Validator\Constraints as Assert;

/**
 * @ApiResource(attributes={"validation_groups"={"a", "b"}})
 * ...
 */
class Book
{
    /**
     * @Assert\NotBlank(groups={"a"})
     */
    public $name;

    /**
     * @Assert\NotNull(groups={"b"})
     */
    public $author;

    // ...
}

With the previous configuration, the validation groups a and b will be used when validation is performed.

Like for serialization groups, you can specify validation groups globally or on a per-operation basis.

Of course, you can use XML or YAML configuration format instead of annotations if you prefer.

You may also pass in a group sequence in place of the array of group names.

Using Validation Groups on Operations

You can have different validation for each operation related to your resource.

<?php
// api/src/Entity/Book.php

use ApiPlatform\Core\Annotation\ApiResource;
use Symfony\Component\Validator\Constraints as Assert;

/**
 * @ApiResource(
 *     collectionOperations={
 *         "get",
 *         "post"={"validation_groups"={"Default", "postValidation"}}
 *     },
 *     itemOperations={
 *         "delete",
 *         "get",
 *         "put"={"validation_groups"={"Default", "putValidation"}}
 *     }
 * )
 * ...
 */
class Book
{
    /**
     * @Assert\Uuid
     */
    private $id;

    /**
     * @Assert\NotBlank(groups={"postValidation"})
     */
    public $name;

    /**
     * @Assert\NotNull
     * @Assert\Length(
     *     min = 2,
     *     max = 50,
     *     groups={"postValidation"}
     * )
     * @Assert\Length(
     *     min = 2,
     *     max = 70,
     *     groups={"putValidation"}
     * )
     */
    public $author;

    // ...
}

With this configuration, there are three validation groups:

Default contains the constraints that belong to no other group.

postValidation contains the constraints on the name and author (length from 2 to 50) fields only.

putValidation contains the constraints on the author (length from 2 to 70) field only.

Dynamic Validation Groups

If you need to dynamically determine which validation groups to use for an entity in different scenarios, just pass in a callable. The callback will receive the entity object as its first argument, and should return an array of group names or a group sequence.

In the following example, we use a static method to return the validation groups:

<?php
// api/src/Entity/Book.php

use ApiPlatform\Core\Annotation\ApiResource;
use Symfony\Component\Validator\Constraints as Assert;

/**
 * @ApiResource(
 *     attributes={"validation_groups"={Book::class, "validationGroups"}}
 * )
 */
class Book
{
    /**
     * Return dynamic validation groups.
     *
     * @param self $book Contains the instance of Book to validate.
     *
     * @return string[]
     */
    public static function validationGroups(self $book)
    {
        return ['a'];
    }

    /**
     * @Assert\NotBlank(groups={"a"})
     */
    public $name;

    /**
     * @Assert\NotNull(groups={"b"})
     */
    public $author;

    // ...
}

Alternatively, you can use a service to retrieve the groups to use:

<?php
// api/src/Validator/AdminGroupsGenerator.php

namespace App\Validator;

use App\Entity\Book;
use Symfony\Component\Security\Core\Authorization\AuthorizationCheckerInterface;

final class AdminGroupsGenerator
{
    private $authorizationChecker;

    public function __construct(AuthorizationCheckerInterface $authorizationChecker)
    {
        $this->authorizationChecker = $authorizationChecker;
    }

    public function __invoke(Book $book): array
    {
        return $this->authorizationChecker->isGranted('ROLE_ADMIN', $book) ? ['a', 'b'] : ['a'];
    }
}

This class selects the groups to apply based on the role of the current user: if the current user has the ROLE_ADMIN role, groups a and b are returned. In other cases, just a is returned.

This class is automatically registered as a service thanks to the autowiring feature of the Symfony Dependency Injection Component. Just note that this service must be public.

Then, configure the entity class to use this service to retrieve validation groups:

<?php
// api/src/Entity/Book.php

namespace App\Entity;

use ApiPlatform\Core\Annotation\ApiResource;
use App\Validator\AdminGroupsGenerator;
use Symfony\Component\Validator\Constraints as Assert;

/**
 * @ApiResource(attributes={"validation_groups"=AdminGroupsGenerator::class})
 */
class Book
{
    /**
     * @Assert\NotBlank(groups={"a"})
     */
    public $name;

    /**
     * @Assert\NotNull(groups={"b"})
     */
    public $author;

    // ...
}

Sequential Validation Groups

If you need to specify the order in which your validation groups must be tested against, you can use a group sequence. First, you need to create your sequenced group.

<?php

declare(strict_types=1);

namespace App\Validator;

use Symfony\Component\Validator\Constraints\GroupSequence;

class MySequencedGroup
{
    public function __invoke()
    {
        return new GroupSequence(['first', 'second']); // now, no matter which is first in the class declaration, it will be tested in this order.
    }
}

Just creating the class is not enough because Symfony does not see this service as being used. Therefore to prevent the service to be removed, you need to enforce it to be public.

# api/config/services.yaml
services:
    App\Validator\MySequencedGroup: ~
        public: true

And then, you need to use your class as a validation group.

<?php

namespace App\Entity;

use ApiPlatform\Core\Annotation\ApiResource;
use App\Validator\One; // classic custom constraint
use App\Validator\Two; // classic custom constraint
use App\Validator\MySequencedGroup; // the sequence group to use
use Doctrine\ORM\Mapping as ORM;

/**
 * @ApiResource(
 *     collectionOperations={
 *          "post" = {
 *              "validation_groups" = MySequencedGroup::class
 *          }
 *     }
 * )
 * @ORM\Entity
 */
class Greeting
{
    /**
     * @var int The entity Id
     *
     * @ORM\Id
     * @ORM\GeneratedValue
     * @ORM\Column(type="integer")
     */
    private $id;

    /**
     * @var string A nice person
     *
     * @ORM\Column
     * 
     * I want this "second" validation to be executed after the "first" one even though I wrote them in this order.
     * @One(groups={"second"})
     * @Two(groups={"first"})
     */
    public $name = '';

    public function getId(): int
    {
        return $this->id;
    }
}

Error Levels and Payload Serialization

As stated in the Symfony documentation, you can use the payload field to define error levels. You can retrieve the payload field by setting the serialize_payload_fields to an empty array in the API Platform config:

# api/config/packages/api_platform.yaml

api_platform:
    validator:
        serialize_payload_fields: ~

Then, the serializer will return all payload values in the error response.

If you want to serialize only some payload fields, define them in the config like this:

# api/config/packages/api_platform.yaml

api_platform:
    validator:
        serialize_payload_fields: [ severity, anotherPayloadField ]

In this example, only severity and anotherPayloadField will be serialized.

Validation on Collection Relations

Use the Valid constraint.

Note: this is related to the collection relation denormalization. You may have an issue when trying to validate a relation representing a Doctrine’s ArrayCollection (toMany). Fix the denormalization using the property getter. Return an array instead of an ArrayCollection with $collectionRelation->getValues(). Then, define your validation on the getter instead of the property.

For example:

<getter property="cars">
    <constraint name="Valid"/>
</getter>

<?php

namespace App\Entity;

use Doctrine\Common\Collections\ArrayCollection;
use Symfony\Component\Validator\Constraints as Assert;

final class Brand
{
    // ...

    public function __construct()
    {
        $this->cars = new ArrayCollection();
    }

    /**
     * @Assert\Valid
     */
    public function getCars()
    {
        return $this->cars->getValues();
    }
}

Open Vocabulary Generated from Validation Metadata

API Platform automatically detects Symfony’s built-in validators and generates schema.org IRI metadata accordingly. This allows for rich clients such as the Admin component to infer the field types for most basic use cases.

The following validation constraints are covered:

Constraints	Vocabulary
`Url`	`http://schema.org/url`
`Email`	`http://schema.org/email`
`Uuid`	`http://schema.org/identifier`
`CardScheme`	`http://schema.org/identifier`
`Bic`	`http://schema.org/identifier`
`Iban`	`http://schema.org/identifier`
`Date`	`http://schema.org/Date`
`DateTime`	`http://schema.org/DateTime`
`Time`	`http://schema.org/Time`
`Image`	`http://schema.org/image`
`File`	`http://schema.org/MediaObject`
`Currency`	`http://schema.org/priceCurrency`
`Isbn`	`http://schema.org/isbn`
`Issn`	`http://schema.org/issn`

You can also help us improve the documentation of this page.