JSON:API TypeScript Types

Common errors

• Type '{ result: string; }' is not assignable to type 'Document'. Object literal may only specify known properties, and 'result' does not exist in type 'Document'.

  cause Attempting to assign an object that does not conform to the JSON:API Document structure (e.g., using unknown top-level keys).
  fix Ensure the top-level document contains 'data', 'errors', or 'meta' members as per JSON:API specification.

• Type 'string' is not assignable to type 'ResourceObject | ResourceObject[] | ResourceIdentifierObject | ResourceIdentifierObject[] | null | undefined'.

  cause Assigning an incorrect type to a field expected to be a JSON:API primary data or relationship data (e.g., assigning a string where a ResourceObject is expected).
  fix Ensure that `data` and relationship `data` fields correctly specify `ResourceObject` or `ResourceIdentifierObject` types, or arrays thereof, as defined by JSON:API.

• Property 'id' is missing in type '{ type: "articles"; }' but required in type 'ResourceObject<any, object>'.

  cause Creating a `ResourceObject` without the mandatory `id` property.
  fix All `ResourceObject` and `ResourceIdentifierObject` types must include both `type` and `id` properties.

Warnings

• breaking The package appears to be abandoned, with no updates since April 2019. It may not be compatible with newer TypeScript versions (beyond TS 2.3 mentioned) or the latest JSON:API specification (v1.1 published July 2020).
  Fix: Consider alternatives like `ts-japi` or `ts-json-api` for actively maintained and up-to-date JSON:API type solutions.
• gotcha This package only provides type definitions; it does not include any runtime parsing, serialization, or client functionality. It's solely for compile-time validation.
  Fix: Pair this with a separate JSON:API client or serialization library if runtime operations are needed. Or use a library that combines types with runtime logic.
• gotcha The type definitions might not fully encompass all optional or advanced features of the JSON:API specification (e.g., custom extensions, profiles) as the project predates later spec revisions.
  Fix: Manually extend or augment types if specific advanced JSON:API features not covered by this package are required.

Install

• npm install jsonapi-typescript npm
• yarn add jsonapi-typescript yarn
• pnpm add jsonapi-typescript pnpm

Imports

• JSONAPI
  wrong:

  const JSONAPI = require('jsonapi-typescript');

  correct:

  import * as JSONAPI from 'jsonapi-typescript';

  Primarily designed for ESM and TypeScript; CommonJS `require` won't provide type-checking.
• Document
  wrong:

  import JSONAPI from 'jsonapi-typescript';

  correct:

  import { Document } from 'jsonapi-typescript';

  Specific types like `Document` are named exports. The package does not have a default export.
• ResourceObject

  import { ResourceObject } from 'jsonapi-typescript';

  Commonly used for defining the structure of individual resources within a JSON:API document.

Quickstart

Demonstrates importing the type definitions and validating a basic JSON:API document structure at compile-time.

import * as JSONAPI from 'jsonapi-typescript';

// ✅ This should be OK (a valid single-resource JSON:API document)
let validDoc: JSONAPI.Document = {
  data: {
    type: 'articles',
    id: '1',
    attributes: {
      title: 'Hello World'
    },
    relationships: {
      author: {
        data: { type: 'people', id: '9' }
      }
    }
  }
};

// ⛔️ This should NOT be OK (missing 'data' or 'errors' top-level keys, 'result' is invalid)
// let invalidDoc1: JSONAPI.Document = {
//   result: "Success!"
// };

// ⛔️ This should NOT be OK (empty Array is not a valid JSON:API document root)
// let invalidDoc2: JSONAPI.Document = [];

console.log('Valid JSON:API document example:', JSON.stringify(validDoc, null, 2));