About

The JSON:API specification enforces a compound document structure where resources are split across data and included arrays, with relationships expressed as type+id linkage objects. Backbone.js models and collections expect flat attribute hashes. Manually denormalizing these responses introduces bugs: missed includes produce NULL nested objects, circular relationships cause infinite loops, and polymorphic collections silently drop records when the type key is ignored. This converter resolves every relationship linkage against the included pool, flattens attributes to the root level, and detects reference cycles using a visited-set algorithm. It handles single-resource documents, resource-collection documents, and sparse fieldsets without data loss.

Limitations: this tool operates on static JSON text. It does not fetch remote URLs or handle server-sent streaming responses. Deeply nested circular relationships are detected and truncated with a [Circular] marker rather than causing a stack overflow. The maximum practical input size is approximately 50MB depending on browser memory. For payloads exceeding 500KB, conversion runs in a Web Worker to avoid UI freezing.

Formulas

The denormalization algorithm constructs an include-map M and recursively resolves each resource R:

buildMap(included) → M = { type:id ↦ resource }

For each resource in data (or the single resource object):

flatten(R, M, visited) = { id: R.id, ...R.attributes, ...resolveRels(R.relationships, M, visited) }

Relationship resolution per key k:

{

k → null if linkage = nullk → flatten(M[type:id]) if linkage is objectk → linkage.map(l → flatten(M[l.type:l.id])) if linkage is array

Cycle detection: before recursing into any resource, the composite key type:id is checked against visited (a Set). If present, a [Circular] marker replaces the nested object, preventing infinite recursion. The visited set is scoped per resolution path, not globally, allowing the same resource to appear in sibling branches.

In reference mode, instead of embedding, the algorithm outputs: k_id = linkage.id (for to-one) or k_ids = [linkage₀.id, linkage₁.id, ...] (for to-many).

Reference Data

JSON:API Field	Location in Source	Backbone Output Mapping	Notes
data.id	Top-level resource	id (root key)	Always preserved as string
data.type	Top-level resource	_type (optional)	Included if "Preserve type" enabled
data.attributes.*	Nested in resource	Flattened to root keys	Key names unchanged
data.relationships.X.data	Linkage object	Embedded object or X_id	Mode: embed vs. reference
data.relationships.X.data[]	Linkage array	Array of objects or X_ids	Plural relationships
data.links	Resource links	_links (optional)	Only if "Preserve links" enabled
data.meta	Resource meta	_meta (optional)	Only if "Preserve meta" enabled
included[]	Top-level array	Resolved into relationships	Lookup by type:id
included[].attributes	Included resource	Flattened into nested object	Recursive resolution
included[].relationships	Included resource	Recursively resolved	Cycle detection applied
jsonapi	Top-level	Discarded	Server metadata not relevant to models
errors	Top-level	Passed through as-is	Error responses are not converted
links (top-level)	Document links	_documentLinks (optional)	Pagination links etc.
meta (top-level)	Document meta	_documentMeta (optional)	Total counts, cursors etc.
Null relationship	data: null	NULL	Preserved as null
Empty to-many	data: []	Empty array []	Preserved as empty array
Polymorphic to-many	Mixed type in array	Mixed embedded objects	Each resolved by own type
Missing include	Linkage with no match	{ id, _type } stub	Warning emitted in console

Frequently Asked Questions

The algorithm maintains a per-path visited Set keyed by the composite string type:id. When a resource is about to be resolved recursively and its key already exists in the current path's visited set, it is replaced with a { "_circular": "type:id" } marker object. This prevents stack overflow while preserving information about which resource was circularly referenced. Sibling branches can still independently resolve the same resource.

A stub object is produced containing only the id and _type fields from the linkage object. A warning is added to the conversion log visible in the UI. This matches real-world scenarios where servers use sparse includes or the client requested specific include paths via the include query parameter.

Embed mode produces fully nested objects matching Backbone's RelationalModel pattern where associated models are instantiated from inline data. Reference mode produces foreign-key style output (author_id, tag_ids) suitable for Backbone models that lazily fetch associations. Embed mode increases payload size proportionally to relationship depth. Reference mode keeps output flat but requires separate collection fetches.

By default, resource-level meta and links are discarded because Backbone models typically ignore them. Toggle "Preserve meta" or "Preserve links" to include them as _meta and _links keys respectively. Top-level document meta and links (e.g., pagination) can be preserved as _documentMeta and _documentLinks on the wrapper object.

When a relationship's data array contains linkage objects with different type values, each is resolved independently against the included map. The resulting array may contain objects with different structures. A _type field is automatically added to each embedded object in polymorphic arrays so consuming code can distinguish between resource types.

For inputs under 500 KB, conversion runs synchronously on the main thread with sub-millisecond latency for typical API responses. Inputs between 500 KB and approximately 50 MB are offloaded to a Web Worker. Beyond 50 MB, browser memory constraints may cause failures depending on available RAM. The tool reports parsing time and output size after each conversion.