Package org.apache.juneau.bean.jsonapi

package org.apache.juneau.bean.jsonapi
Juneau @Marshalled types for the JSON:API v1.1 wire format.
Overview

JSON:API is a media-type (application/vnd.api+json) for building APIs with shared conventions for resources, relationships, links, errors, and metadata. This module provides typed Juneau beans modeling the JSON:API wire format - no marshaller is needed; the existing JsonSerializer / JsonParser already produce and consume the wire format. The matching ContentType constant is org.apache.juneau.http.header.ContentType#APPLICATION_VND_API_JSON.

Bean Classes
Important: JsonApiResource.type is a plain String

JSON:API uses type as an open-ended string field on resource objects (the entity-type name, e.g. "articles"); the value is chosen by the API and is not a closed Java class hierarchy. Therefore JsonApiResource models type as a plain String and is not annotated with @Marshalled(typePropertyName="type", dictionary=...). Conflating JSON:API resource typing with Juneau bean dispatch would break round-tripping of unknown type values and force every API to enumerate its resource types in a Java dictionary up front.

Document-level mutual exclusion

Per the JSON:API spec, a document MUST contain at least one of data, errors, or meta; data and errors MUST NOT coexist. JsonApiDocument documents this constraint and offers an optional validate() helper.

Example

// Build a compound document with included resources. JsonApiResource article = new JsonApiResource() .setType("articles").setId("1") .putAttribute("title", "JSON:API paints my bikeshed!"); JsonApiDocument doc = new JsonApiDocument().setData(article); String json = JsonSerializer.DEFAULT.write(doc);

See Also: