Adding new formats

Last updated on
13 October 2016

Core supports JSON and XML, as well as HAL-JSON. It is easy to add support for other formats.

Adding basic support

As explained in How the Serializer works, the serialization process has two parts, normalization and encoding.

If the array structure created by core's default Normalizers is acceptable for your format, then you can simply add an Encoder.

  1. Create an encoder

    Your Encoder should implement EncoderInterface. See Drupal\hal\Encoder for a simple example. Note that its parent class defines the required encode and decode methods.

  2. Register the encoder

    You must register your custom encoder via a *.services.yml file. See serializer.encoder.hal in for an example. If you want this format to be configurable via REST module, you must include the format attribute to the encoder tag.

  3. Register MIME Type

    If the MIME type of your format isn't registered, register it. The default MIME types are defined in Request::initializeFormats(). If the MIME type of your format is not listed there, you need to add it to the Request object. This can be done with an event subscriber.

     * Event subscriber for adding additional content types to the request.
    class MySubscriber implements EventSubscriberInterface {
       * Register content type formats on the request object.
       * @param \Symfony\Component\HttpKernel\Event\GetResponseEvent $event
       *   The Event to process.
      public function onKernelRequest(GetResponseEvent $event) {
        $event->getRequest()->setFormat('myformat', array('text/myformat'));
       * Implements \Symfony\Component\EventDispatcher\EventSubscriberInterface::getSubscribedEvents().
      static function getSubscribedEvents() {
        $events[KernelEvents::REQUEST][] = array('onKernelRequest');
        return $events;

    Your event subscriber must also be registered via *.services.yml.