home / skills / shipshitdev / library / serializer-specialist

serializer-specialist skill

safe

/bundles/backend/skills/serializer-specialist

This skill helps you design and build JSON:API serializers with shared configurations for client and server, ensuring consistent relationships and attributes.

npx playbooks add skill shipshitdev/library --skill serializer-specialist

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

1.3 KB

---
name: serializer-specialist
description: Expert in JSON:API serialization patterns using ts-jsonapi or similar libraries.
---

# Serializer Specialist

You design JSON:API serializer configurations for shared client and server packages.

## When to Use

- Adding or updating JSON:API serializers
- Modeling relationships and attributes
- Implementing serializer builders

## Core Concepts

- Keep attributes and relationships explicit.
- Use shared configs for consistency.
- Distinguish client and server id fields if needed.

## Pattern

1) Attribute list
2) Config with relationships
3) Build serializer for target package

### Attribute Definitions

```ts
export const articleAttributes = ["title", "status", "createdAt", "updatedAt"];
```

### Serializer Config

```ts
export const articleSerializerConfig = {
  type: "article",
  attributes: articleAttributes,
  author: {
    ref: "id",
    type: "user",
    attributes: ["name", "email"]
  }
};
```

### Build Serializer

```ts
import { buildSerializer } from "@org/serializers";
import { articleSerializerConfig } from "@org/serializers";

export const { ArticleSerializer } = buildSerializer("server", articleSerializerConfig);
```

## Checklist

- Config matches JSON:API expectations
- Relationship types and refs are consistent
- Shared configs live in one package
- Serializers are reusable across services

Overview

This skill designs JSON:API serializer configurations and builders for shared client and server packages. It focuses on explicit attribute lists, relationship definitions, and reusable serializer factories to keep serialization consistent across services. The goal is predictable payloads and easy reuse with libraries like ts-jsonapi or similar patterns in other languages.

How this skill works

I define canonical attribute arrays and a serializer config object that declares type, attributes, and relationships with ref and type. A build step produces serializers targeted to a package (for example 'client' or 'server'), ensuring id/ref conventions match each runtime. Shared configs live in a central package so clients and servers reuse identical contracts.

When to use it

Adding or updating JSON:API serializers for a resource
Modeling relationships (belongs-to, has-many) and their refs
Creating shared serializer configs for multi-service projects
Generating client- or server-targeted serializer implementations
Enforcing consistent attribute exposure and payload shapes

Best practices

Keep attributes explicit in arrays to avoid accidental exposure
Define relationship entries with clear ref and type fields
Store shared configs in a single package consumed by both client and server
Distinguish client/server id conventions via the build target
Validate configs against JSON:API expectations before publishing

Example use cases

Define articleAttributes = ['title','status','createdAt','updatedAt'] and reuse across services
Create articleSerializerConfig with an author relationship { ref: 'id', type: 'user', attributes: [...] }
Run buildSerializer('server', config) to generate server serializers and buildSerializer('client', config) for client SDKs
Centralize relationship type strings to prevent typos and maintain compatibility
Use shared configs in integration tests to assert payload parity

FAQ

How do I model a has-many relationship?

Declare the relationship in the config with the related type and ref. Use arrays of resource identifiers in the serialized output and ensure the build target knows how to resolve collections.

Where should shared configs live?

Place them in a dedicated shared serializers package that both client and server packages depend on to ensure one source of truth.