json_api_document 0.3.2

  • README.md
  • Example
  • Installing
  • Versions
  • 81

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).');


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.


0.3.2 - 2018-11-05


  • Minor documentation improvements

0.3.0 - 2018-11-05


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


  • Link.isObject
  • Link.meta

0.2.2 - 2018-10-09


  • 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


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

0.2.0 - 2018-10-03


  • 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.2

2. Install it

You can install packages from the command line:

with pub:

$ pub get

with Flutter:

$ flutter packages get

Alternatively, your editor might support pub get or flutter packages 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';
Version Uploaded Documentation Archive
0.3.2 Nov 6, 2018 Go to the documentation of json_api_document 0.3.2 Download json_api_document 0.3.2 archive
0.3.1 Nov 6, 2018 Go to the documentation of json_api_document 0.3.1 Download json_api_document 0.3.1 archive
0.3.0 Nov 6, 2018 Go to the documentation of json_api_document 0.3.0 Download json_api_document 0.3.0 archive
0.2.2 Oct 10, 2018 Go to the documentation of json_api_document 0.2.2 Download json_api_document 0.2.2 archive
0.2.1 Oct 5, 2018 Go to the documentation of json_api_document 0.2.1 Download json_api_document 0.2.1 archive
0.2.0 Oct 3, 2018 Go to the documentation of json_api_document 0.2.0 Download json_api_document 0.2.0 archive
0.1.2 Oct 2, 2018 Go to the documentation of json_api_document 0.1.2 Download json_api_document 0.1.2 archive
0.1.1 Oct 2, 2018 Go to the documentation of json_api_document 0.1.1 Download json_api_document 0.1.1 archive
0.1.0 Oct 2, 2018 Go to the documentation of json_api_document 0.1.0 Download json_api_document 0.1.0 archive
0.0.8 Oct 2, 2018 Go to the documentation of json_api_document 0.0.8 Download json_api_document 0.0.8 archive

All 17 versions...

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 Nov 14, 2018, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.0.0
  • pana: 0.12.6


Detected platforms: Flutter, web, other

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


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