json_api_document 0.3.0

JSON API Document model and parser

The goal of this library is to provide a transparent way to build and parse JSON API Documents.

These are the key values of the library:

  • Immutability. Produced documents are immutable value objects.
  • Native JSON support. Use the built-in json.encode() to convert to a JSON string.
  • Strict standard compliance. All JSON API Documents are guaranteed to follow JSON API v1.0.

Building JSON API Document #

To get a sense of what the library API looks like, take a look at the example:

import 'dart:convert';

import 'package:json_api_document/json_api_document.dart';

/// The following function produces the example document
/// from the first page of http://jsonapi.org/.
Document makeJsonApiResponse() {
  final dan = Resource('people', '9',
      attributes: {
        'first-name': 'Dan',
        'last-name': 'Gebhardt',
        'twitter': 'dgeb'
      self: Link('http://example.com/people/9'));

  final personIdentifier = Identifier('people', '2');

  final firstComment = Resource('comments', '5',
      attributes: {'body': 'First!'},
      relationships: {'author': ToOne(personIdentifier)},
      self: Link('http://example.com/comments/5'));

  final secondComment = Resource('comments', '12',
      attributes: {'body': 'I like XML better'},
      relationships: {'author': ToOne(Identifier.of(dan))},
      self: Link('http://example.com/comments/12'));

  final article = Resource(
    self: Link('http://example.com/articles/1'),
    attributes: {'title': 'JSON API paints my bikeshed!'},
    relationships: {
      'author': ToOne(
        self: Link('http://example.com/articles/1/relationships/author'),
        related: Link('http://example.com/articles/1/author'),
      'comments': ToMany(
          [Identifier.of(firstComment), Identifier.of(secondComment)],
          self: Link('http://example.com/articles/1/relationships/comments'),
          related: Link('http://example.com/articles/1/comments'))

  return DataDocument.fromResourceList([article],
      self: Link('http://example.com/articles'),
      next: Link('http://example.com/articles?page[offset]=2'),
      last: Link('http://example.com/articles?page[offset]=10'),
      included: [dan, firstComment, secondComment]);

/// Print the JSON representation of the response to stdout
void main() {
  final response = makeJsonApiResponse();

This code will produce the following output:

  "links": {
    "self": "http://example.com/articles",
    "next": "http://example.com/articles?page[offset]=2",
    "last": "http://example.com/articles?page[offset]=10"
  "data": [
      "type": "articles",
      "id": "1",
      "attributes": {"title": "JSON API paints my bikeshed!"},
      "relationships": {
        "author": {
          "links": {
            "related": "http://example.com/articles/1/author"
          "data": {"type": "people", "id": "9"}
        "comments": {
          "links": {
            "related": "http://example.com/articles/1/comments"
          "data": [
            {"type": "comments", "id": "5"},
            {"type": "comments", "id": "12"}
      "links": {"self": "http://example.com/articles/1"}
  "included": [
      "type": "people",
      "id": "9",
      "attributes": {
        "first-name": "Dan",
        "last-name": "Gebhardt",
        "twitter": "dgeb"
      "links": {"self": "http://example.com/people/9"}
      "type": "comments",
      "id": "5",
      "attributes": {"body": "First!"},
      "relationships": {
        "author": {
          "data": {"type": "people", "id": "2"}
      "links": {"self": "http://example.com/comments/5"}
      "type": "comments",
      "id": "12",
      "attributes": {"body": "I like XML better"},
      "relationships": {
        "author": {
          "data": {"type": "people", "id": "9"}
      "links": {"self": "http://example.com/comments/12"}

Parsing JSON API Document #

This example reads the JSON API from stdin and prints some details about it:

import 'dart:convert';
import 'dart:io';

import 'package:json_api_document/json_api_document.dart';

void main() async {
  final jsonString = await stdin.transform(Utf8Decoder()).join();
  final jsonObject = json.decode(jsonString);
  final doc = Document.fromJson(jsonObject);
  print('This is ${doc.runtimeType}');
  if (doc is DataDocument) {
    print('The primary data is ${doc.data.runtimeType} ' +
        'with ${doc.data.resources.length} resource(s).');
    print('The document contains ${doc.included.length} included resource(s).');

Changelog #

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog and this project adheres to Semantic Versioning.

Unreleased #

0.3.0 - 2018-11-05

Added #

  • Parsing capabilities.
  • A few accessors to Meta, Attributes, Relationships

Removed #

  • Link.isObject
  • Link.meta

0.2.2 - 2018-10-09

Added #

  • Enforce naming rules on relationships
  • Included resources are checked for duplicates
  • LinkObject
  • Pagination links for data collection documents
  • Resource fields uniqueness enforcement

0.2.1 - 2018-10-05

Added #

  • Compound documents
  • Meta property to Identifier
  • Prohibit creating empty Api objects

0.2.0 - 2018-10-03 #

Added #

  • Initial usable implementation


Building stuff #

build.dart builds a new JSON API Document and prints its JSON representation.


dart example/build.dart

to produce a sample JSON API Document. For your convenience, document.json already contains the pretty-printed version of this document.

Parsing stuff #

parse.dart parses any JSON API document from the standard input.


dart example/parse.dart < example/document.json

to parse the example document. This will produce the following output:

This is DataDocument
The primary data is ResourceListData with 1 resource(s).
The document contains 3 included resource(s).

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:

  json_api_document: ^0.3.0

2. Install it

You can install packages from the command line:

with pub:

$ pub get

with Flutter:

$ flutter pub get

Alternatively, your editor might support pub get or flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:

import 'package:json_api_document/json_api_document.dart';
Describes how popular the package is relative to other packages. [more]
Code health derived from static analysis. [more]
Reflects how tidy and up-to-date the package is. [more]
Weighted score of the above. [more]
Learn more about scoring.

We analyzed this package on Jul 11, 2019, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.4.0
  • pana: 0.12.19


Detected platforms: Flutter, web, other

No platform restriction found in primary library package:json_api_document/json_api_document.dart.

Health suggestions

Fix lib/src/relationship.dart. (-1 points)

Analysis of lib/src/relationship.dart reported 2 hints:

line 15 col 17: Don't type annotate initializing formals.

line 15 col 33: Don't type annotate initializing formals.

Fix lib/src/data_document.dart. (-0.50 points)

Analysis of lib/src/data_document.dart reported 1 hint:

line 119 col 26: Don't type annotate initializing formals.

Fix lib/src/error_object.dart. (-0.50 points)

Analysis of lib/src/error_object.dart reported 1 hint:

line 60 col 9: Use isNotEmpty instead of length

Fix additional 4 files with analysis or formatting issues. (-2 points)

Additional issues in the following files:

  • lib/src/identifier_data.dart (1 hint)
  • lib/src/naming.dart (1 hint)
  • lib/src/resource.dart (1 hint)
  • lib/src/resource_data.dart (1 hint)


Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.0.0 <3.0.0
Dev dependencies
json_matcher >=0.2.2
pubspec_version ^0.1.0
test 1.3.0