jsonapi-serializer

3.6.9 verified Sat Apr 25 auth: no javascript maintenance

A Node.js framework-agnostic library for serializing and deserializing data to JSON API 1.0 compliant format. Current stable version is 3.6.9, maintained with infrequent releases (last in 2020). Differentiators include heavy customization options (custom attribute keys via keyForAttribute, transforms, top-level links, nested relationships) and support for both serialization and deserialization. Compared to alternatives like jsonapi-store-relationaldb or fast-jsonapi, it offers more fine-grained control over meta, links, and relationship configuration.

Common errors

error Error: The 'type' argument is required ↓

cause Missing or invalid first argument to Serializer constructor.

fix

new Serializer('resourceType', opts)

error TypeError: Cannot read property 'attributes' of undefined ↓

cause Serializer called on undefined or null data, or 'data' field missing from input.

fix

Pass a valid object or array to serializer.serialize(data).

error Error: You must provide an 'id' for the resource ↓

cause Data object missing 'id' field while 'ref' is set in relationship options.

fix

Ensure each resource object has an 'id' field, or adjust relationship 'ref' to another unique field.

error ReferenceError: require is not defined ↓

cause Trying to use CommonJS require in an ES module context (e.g., type: module in package.json).

fix

Use import syntax instead: import { Serializer } from 'jsonapi-serializer'

Warnings

breaking In v3, the 'type' field is mandatory and must be a string; v2 accepted objects. Also, 'id' parameter for relationships becomes required. ↓

fix Update to v3 and ensure 'type' is a string and 'ref' inside relationships points to 'id' field.

deprecated The 'keyForAttribute' option with value 'dasherize' (or 'dash-case') is deprecated in v3.6.0 in favor of direct string 'dash-case'. ↓

fix Use 'keyForAttribute: 'dash-case'' instead of 'dasherize'.

gotcha If you omit 'attributes' array, the serializer will include all properties from the input data, including nested objects that might not be valid JSON API. ↓

fix Always define 'attributes' list to control output and avoid inclusion of unintended fields.

gotcha In v3, the 'included' option defaults to true for relationships. If you set 'included: false', the relationship data will still be present under 'relationships' but not in 'included' top-level array. ↓

fix Explicitly set 'included: false' if you do not want full inclusion.

gotcha The library does not support circular references; it will throw a RangeError: Maximum call stack size exceeded. ↓

fix Ensure your data structures are acyclic or use a custom transform to prune cycles.

Install

npm install jsonapi-serializer

yarn add jsonapi-serializer

pnpm add jsonapi-serializer

Imports

Serializer
wrong
```
const Serializer = require('jsonapi-serializer').Serializer
```
correct
```
import { Serializer } from 'jsonapi-serializer'
```
ESM import works in Node >=12 with type module; CommonJS require is supported for older Node versions.

Deserializer

wrong

const Deserializer = require('jsonapi-serializer').Deserializer

correct

import { Deserializer } from 'jsonapi-serializer'

Same import pattern as Serializer.

Error

wrong

import Error from 'jsonapi-serializer'

correct

import { Error } from 'jsonapi-serializer'

The Error class is a named export, not default.

Quickstart

Serializes an article object with included author relationship to JSON API format.

import { Serializer } from 'jsonapi-serializer';
const serializer = new Serializer('articles', {
  attributes: ['title', 'body', 'author'],
  author: {
    ref: 'id',
    included: true,
    attributes: ['firstName', 'lastName']
  }
});
const data = {
  id: '1',
  title: 'JSON API is awesome',
  body: 'It works!',
  author: {
    id: '2',
    firstName: 'Sandro',
    lastName: 'Munda'
  }
};
const serialized = serializer.serialize(data);
console.log(JSON.stringify(serialized, null, 2));