Registry / serialization / jsonapi-serializer

jsonapi-serializer

library3.6.9jsnpmunverified

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.

serialization

npm install jsonapi-serializer

github ↗package ↗

INSTALL

IMPORT

SIG · JSONAPI-SERIALIZER

jsonapi-serializer

serializationjavascriptv3.6.9

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Serializer

✓ import { Serializer } from 'jsonapi-serializer'

✗ const Serializer = require('jsonapi-serializer').Serializer

ESM import works in Node >=12 with type module; CommonJS require is supported for older Node versions.

Deserializer

✓ import { Deserializer } from 'jsonapi-serializer'

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

Same import pattern as Serializer.

Error

✓ import { Error } from 'jsonapi-serializer'

✗ import Error from 'jsonapi-serializer'

The Error class is a named export, not default.

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));

Debug

Known issues

breakingIn 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.

affects: <3.0.0

deprecatedThe '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'.

affects: >=3.6.0

gotchaIf 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.

affects: >=3.0.0

gotchaIn 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.

affects: >=3.0.0

gotchaThe 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.

affects: >=3.0.0

Errors

Common errors & fixes

Error: The 'type' argument is required

Missing or invalid first argument to Serializer constructor.

fix

new Serializer('resourceType', opts)

TypeError: Cannot read property 'attributes' of undefined

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: You must provide an 'id' for the resource

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.

ReferenceError: require is not defined

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'

Upgrade

Version history

3.6.9latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/SeyZ/jsonapi-serializer ↗

packagehttps://www.npmjs.com/package/jsonapi-serializer ↗