Skill serialization-groups
Configura contextos de serialização e desserialização usando grupos para controlar a visibilidade de campos e o aninhamento de relações no API Platform.
- Estrelas no GitHub
- 29
- Arquivos
- 1
- Último commit
- 22 de out. de 2026
- Licença
- —
- Ferramentas permitidas
- —
O que a skill serialization-groups faz?
Configura contextos de serialização e desserialização usando grupos para controlar a visibilidade de campos e o aninhamento de relações no API Platform.
Resumo gerado a partir do SKILL.md da skill.
Sobre a skill serialization-groups
Gerenciar a visibilidade de campos e o aninhamento de relações no API Platform é o que este SKILL permite para desenvolvedores que trabalham com Symfony ou Laravel. Ele fornece a lógica para configurar contextos de normalização e desserialização, permitindo que você controle quais propriedades aparecem nos outputs JSON durante leituras ou nos inputs durante escritas. Ao usar o atributo #[Groups], você pode definir regras de visibilidade específicas para diferentes operações, como mostrar mais detalhes em uma visualização de item único do que em uma lista de coleção.
Um agente deve carregar este SKILL quando um desenvolvedor precisar depurar campos JSON ausentes, implementar propriedades de escrita exclusiva como senhas ou gerenciar como entidades relacionadas são incorporadas como objetos versus IRIs. O SKILL lida com cenários complexos, como sobrescritas por propriedade usando o atributo #[Context] para alterar formatos de data ou grupos de serialização aninhados. Ele também fornece orientações específicas para usuários de Laravel, que devem usar #[ApiProperty] porque os modelos Eloquent não possuem propriedades tipadas. Esta abordagem é destinada a manter a consistência em bases de código existentes onde uma divisão por DTO pode ser desnecessária.
O que um agente pode fazer com ela
- 1Controlar a visibilidade de campos por operaçãoConfigure uma visualização de coleção enxuta enquanto fornece um conjunto de dados mais rico para requisições de itens individuais.
- 2Gerenciar propriedades de escrita exclusivaGaranta que dados sensíveis, como senhas, possam ser recebidos durante o input, mas nunca expostos nas respostas da API.
- 3Alternar entre objetos incorporados e IRIsDecida se uma entidade relacionada deve aparecer como um objeto aninhado completo ou como uma simples referência de string.
- 4Aplicar formatação específica por propriedadeSobrescreva as configurações de serialização padrão para um único campo, como alterar um formato de data.
Escrito a partir do SKILL.md da skill. Cada caso de uso é verificado com uma citação dele.
Como instalar a skill serialization-groups
Cada comando copia a pasta da skill para o diretório de skills do cliente. Reinicie o cliente ou inicie uma nova sessão para carregá-la.Instalar a skill serialization-groups no Plugin
/plugin marketplace add api-platform/skillset /plugin install api-platform@api-platform-skillset
Instalar a skill serialization-groups no Claude Code
~/.claude/skills/serialization-groups/SKILL.md
$ npx degit api-platform/skillset/skills/serialization-groups ~/.claude/skills/serialization-groupsInstalar a skill serialization-groups no Claude Code (project)
.claude/skills/serialization-groups/SKILL.md
$ npx degit api-platform/skillset/skills/serialization-groups .claude/skills/serialization-groupsInstalar a skill serialization-groups no Codex
~/.agents/skills/serialization-groups/SKILL.md
$ npx degit api-platform/skillset/skills/serialization-groups ~/.agents/skills/serialization-groupsInstalar a skill serialization-groups no Gemini CLI
~/.gemini/skills/serialization-groups/SKILL.md
$ npx degit api-platform/skillset/skills/serialization-groups ~/.gemini/skills/serialization-groupsInstalar a skill serialization-groups no Claude.ai
npx degit api-platform/skillset/skills/serialization-groups serialization-groups && zip -r serialization-groups.zip serialization-groups # claude.ai → Customize → Skills → + → Create skill → Upload a skill → serialization-groups.zip
Verificações automatizadas
Executado em 16 de nov. de 2026Relatório completo →Ainda não verificada. Uma skill precisa de 80 pontos, nenhum achado grave e dados suficientes para a verificação. Como as verificações funcionam · O que corrigir para ganhar mais pontos
- Repositório de origem vinculado e acessívelapi-platform/skillset/skills/serialization-groups is public and reachablegithub.com/api-platform/skillset/tree/HEAD/skills/serializat ↗Passou
- Licença de código aberto (OSI)No licenseProblema encontrado
- Commit ou release no último anoLast commit 2026-10-22github.com/api-platform/skillset/commits ↗Passou
- Sem baixar e executar nem roubo de credenciais nos scriptsNo scripts in the skill folderPassou
- Sem instruções ocultas no SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/api-platform/skillset/blob/HEAD/skills/serializat ↗Passou
- Ferramentas pré-aprovadas são restritasNo pre-approved tools; the agent asks before using onegithub.com/api-platform/skillset/blob/HEAD/skills/serializat ↗Passou
- O SKILL.md segue o formato Agent SkillsValid name and description; says when to use it; 178 linesgithub.com/api-platform/skillset/blob/HEAD/skills/serializat ↗Passou
SKILL.md
Ver no GitHubSerialization Groups
Prefer one resource class per representation over groups for new designs. Before reaching for groups, consider a DTO split: one class per output shape and per input shape, each with a flat, explicit set of properties (see api-resource). Reasons groups are a poor default:
- The public shape becomes implicit and scattered. To know what
GET /booksreturns you must mentally union every#[Groups]tag across the class hierarchy and cross-reference each operation'snormalizationContext. A dedicatedBookOutputDTO states the shape in one place.- They complicate the metadata. Per-operation contexts, per-property
#[Context], and group inheritance interact in ways that are hard to predict and hard to test.- They block streaming serialization. API Platform's JsonStreamer path needs one static shape per class; a class whose output varies by group can't be streamed and falls back to the slower object normalizer.
Use groups when: you're working in an existing codebase already built on them (stay consistent), or a DTO split is genuinely overkill (one tiny read/write asymmetry on an internal resource). Otherwise, split the class.
The two contexts
normalizationContext governs reading (entity → JSON). denormalizationContext
governs writing (JSON → entity). A property is only serialized/deserialized if
one of its #[Groups] is listed in the active context.
use ApiPlatform\Metadata\ApiResource;
use Symfony\Component\Serializer\Attribute\Groups;
#[ApiResource(
normalizationContext: ['groups' => ['book:read']],
denormalizationContext: ['groups' => ['book:write']],
)]
class Book
{
#[Groups(['book:read'])] // appears in output, ignored on input
public ?int $id = null;
#[Groups(['book:read', 'book:write'])] // read and write
public string $title = '';
#[Groups(['book:write'])] // write-only, e.g. a password
public ?string $secret = null;
}
A property with no group in the active context is invisible: a field present on the entity but absent from the response is almost always a missing read group.
Naming convention
Use resource:operation-style group names — book:read, book:write,
book:item:read. This keeps groups namespaced per resource so a read group on
one class never accidentally pulls properties on another. Pairing a broad
book:read with a narrower book:item:read lets item operations expose more than
collections (see next section).
Per-operation contexts
Override the resource-level context on a single operation. Common pattern: a lean collection, a richer item view.
use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Get;
use ApiPlatform\Metadata\GetCollection;
use ApiPlatform\Metadata\Patch;
#[ApiResource(normalizationContext: ['groups' => ['book:read']])]
#[GetCollection] // book:read only
#[Get(normalizationContext: ['groups' => ['book:read', 'book:item:read']])]
#[Patch(denormalizationContext: ['groups' => ['book:write']])]
class Book
{
#[Groups(['book:read'])]
public string $title = '';
#[Groups(['book:item:read'])] // only on the single-item GET
public ?string $description = null;
}
Controlling embedded relations
A relation is embedded as a full object when the related class has a property in a group shared with the parent's context; otherwise it serializes as an IRI/string. This is how you choose embed-vs-reference:
#[ApiResource(normalizationContext: ['groups' => ['book:read']])]
class Book
{
#[Groups(['book:read'])]
public ?Author $author = null; // embedded only if Author has a 'book:read' property
}
class Author
{
#[Groups(['book:read'])]
public string $name = ''; // this property pulls Author inline
}
Drop the book:read group from Author::$name and author collapses back to an
IRI. This implicit coupling is exactly the kind of thing a DTO split makes explicit.
Per-property context override with #[Context]
#[Context] overrides serializer options for one property without a new group —
useful for date formats or switching the normalization group on a single relation
(embed the same related type at two depths):
use Symfony\Component\Serializer\Attribute\Context;
use Symfony\Component\Serializer\Attribute\Groups;
use Symfony\Component\Serializer\Normalizer\DateTimeNormalizer;
class Book
{
#[Groups(['book:read'])]
#[Context([DateTimeNormalizer::FORMAT_KEY => 'Y-m-d'])]
public ?\DateTimeInterface $publishedAt = null;
#[Groups(['book:read'])]
#[Context(['normalization' => ['groups' => ['author:summary']]])]
public ?Author $author = null; // serialized with author:summary, not book:read
}
The normalization/denormalization keys scope the override to one direction. See
the parallel example in state-provider (Per-Property Serialization Context).
Interaction with other features
- Validation groups are separate from serialization groups — don't reuse the
same names expecting them to align. See operations for
validationContext. securityexpressions on properties (security: "is_granted(...)") gate fields independently of groups; both must pass.
Laravel (Eloquent)
API Platform uses the Symfony Serializer on Laravel too, so normalizationContext /
denormalizationContext, the two-context model, per-operation contexts and embed-vs-IRI
behaviour are identical. The one difference: Eloquent models have no typed
properties, so #[Groups] can't be attached per property. Declare groups at the
class level via #[ApiProperty(serialize: …, property: …)]:
use ApiPlatform\Metadata\ApiProperty;
use ApiPlatform\Metadata\ApiResource;
use Symfony\Component\Serializer\Attribute\Groups;
#[ApiResource(normalizationContext: ['groups' => ['book:read']])]
#[ApiProperty(serialize: new Groups(['book:read']), property: 'title')]
#[ApiProperty(serialize: new Groups(['book:read']), property: 'author')]
class Book extends Model {}
DTO/ApiResource classes (not extending Model) use property-level #[Groups] as
shown above. The name_converter (default SnakeCaseToCamelCaseNameConverter) is set
in config/api-platform.php.
Checklist
- Considered a DTO-per-shape split before adding groups (see api-resource)
- Group names namespaced per resource (
book:read, not bareread) - Write-only secrets carry only the write group
- Embedded-vs-IRI relations verified against actual JSON, not assumed
-
#[Context]used for one-off format/group tweaks instead of a whole new group
Arquivos desta skill
1Perguntas sobre a skill serialization-groups
Como instalo a skill serialization-groups no Claude Code?
Execute npx degit api-platform/skillset/skills/serialization-groups ~/.claude/skills/serialization-groups. O Claude Code carrega skills de ~/.claude/skills (todos os projetos) ou .claude/skills (um projeto) e usa uma skill quando a descrição dela corresponde à tarefa.
Quais clientes podem usar a skill serialization-groups?
Qualquer cliente que leia o formato Agent Skills: Claude Code, Codex, Gemini CLI e claude.ai (envie como ZIP). Scripts da skill são executados apenas onde o cliente permite execução de código.
Qual é a diferença entre normalizationContext e denormalizationContext?
O normalizationContext governa a leitura (entidade para JSON), enquanto o denormalizationContext governa a escrita (JSON para entidade).
Como posso controlar se uma relação será incorporada como um objeto ou retornada como um IRI?
Uma relação é incorporada como um objeto completo se a classe relacionada possuir uma propriedade em um grupo compartilhado com o contexto do pai; caso contrário, ela será serializada como um IRI.
Devo sempre usar grupos de serialização para novos designs?
Não, para novos designs você deve preferir uma classe de recurso por representação (divisão por DTO) em vez de grupos, para evitar formas implícitas e complexidade de metadados.
Como aplico configurações de serialização específicas a uma única propriedade?
Você pode usar o atributo #[Context] para sobrescrever as opções do serializador para uma única propriedade, como formatos de data ou grupos de normalização específicos.