Work with JSON data

In this chapter, learn how to work with JSON (JavaScript Object Notation) data in Dart. Create data models to represent Wikipedia API responses, use dart:convert to decode JSON text into Dart collections, and use pattern matching to extract and validate data.

Before you begin this chapter, ensure you:

• Have completed Chapter 9 and have a working Dart development environment with the dartpedia project.
• Understand basic Dart syntax, including classes and data types.

JSON is a text-based format for representing structured data such as objects, arrays, numbers, and strings. When you interact with web APIs, responses arrive as JSON strings.

In Dart, converting a JSON string into a strongly-typed data model involves two steps:

1. Decode the JSON string into Dart collections. The dart:convert library provides the jsonDecode() function, which parses a raw JSON string into a standard Dart collection:

   • A JSON object ({...}) becomes a Map<String, dynamic>.
   • A JSON array ([...]) becomes a List<dynamic>.
   dart

   import 'dart:convert';
   ​
   const String jsonString = '{"title": "Dart", "pageid": 12345}';
   ​
   // jsonDecode parses the string, cast to a Map<String, Object?>
   final Map<String, Object?> jsonMap =
       jsonDecode(jsonString) as Map<String, Object?>;
   

   content_copy

2. Convert the decoded collections into custom model objects. While you can read values directly from a Map (like jsonMap['title']), using raw maps throughout your application lacks type safety, invites typos, and provides no IDE autocompletion.

   To solve this, Dart applications define data model classes with factory constructors, conventionally named fromJson, that instantiate typed objects from decoded maps:

   dart

   class ArticleSummary {
     final String title;
     final int pageid;
   ​
     ArticleSummary({required this.title, required this.pageid});
   ​
     factory ArticleSummary.fromJson(Map<String, Object?> json) {
       return ArticleSummary(
         title: json['title'] as String,
         pageid: json['pageid'] as int,
       );
     }
   }
   

   content_copy

Dart also supports pattern matching in fromJson constructors, allowing you to validate the shape of the JSON map and extract values in a single, concise step.

The following tasks set up a multi-package workspace and create the data model classes for Wikipedia API responses.

First, create a new Dart package to house the data models.

1. Navigate to the root directory of your project (/dartpedia).

2. Run the following command in your terminal:

   bash

   dart create wikipedia
   

   content_copy

   This command creates a new directory named wikipedia with the basic structure of a Dart package. You should now see a new folder wikipedia in your project root, alongside cli and command_runner.

Dart workspaces allow you to manage multiple related packages within a single project, simplifying dependency management and local development. Now that you're adding your third package, it's a good time to configure your project to use a Dart workspace.

1. Create the root pubspec.yaml file.

   Navigate to the root directory of your project (/dartpedia) and create a new file named pubspec.yaml with the following content:

   yaml

   name: _
   publish_to: none
   ​
   environment:
     sdk: ^3.8.1 # IMPORTANT: Adjust this to match your Dart SDK version or a compatible range
   workspace:
     - cli
     - command_runner
     - wikipedia
   

   content_copy

2. Add workspace resolution to sub-packages.

   For each of your sub-packages (cli, command_runner, and wikipedia), open their respective pubspec.yaml files and add resolution: workspace to pubspec.yaml. This tells Dart to resolve dependencies within the workspace.

   • For cli/pubspec.yaml:

     yaml

     # ... (existing content) ...
     name: cli
     description: A sample command-line application.
     version: 1.0.0
     resolution: workspace # Add this line
     # ... (existing content) ...
     

     content_copy

   • For command_runner/pubspec.yaml:

     yaml

     # ... (existing content) ...
     name: command_runner
     description: A starting point for Dart libraries or applications.
     version: 1.0.0
     resolution: workspace # Add this line
     # ... (existing content) ...
     

     content_copy

   • For wikipedia/pubspec.yaml:

     yaml

     # ... (existing content) ...
     name: wikipedia
     description: A sample command-line application.
     version: 1.0.0
     resolution: workspace # Add this line
     # ... (existing content) ...
     

     content_copy

3. Resolve workspace dependencies.

   Run dart pub get in your project root to resolve dependencies across all packages in the workspace:

   bash

   dart pub get
   

   content_copy

The Wikipedia API returns a JSON object containing a summary of an article. A typical response from the page summary endpoint looks like this:

{
  "titles": {
    "canonical": "Dart_(programming_language)",
    "normalized": "Dart (programming language)",
    "display": "Dart (programming language)"
  },
  "pageid": 37194605,
  "extract": "Dart is a client-optimized language for fast apps...",
  "extract_html": "<p><b>Dart</b> is a client-optimized language...</p>",
  "lang": "en",
  "dir": "ltr",
  "content_urls": {
    "desktop": {
      "page": "https://en.wikipedia.org/wiki/Dart_(programming_language)"
    },
    "mobile": {
      "page": "https://en.m.wikipedia.org/wiki/Dart_(programming_language)"
    }
  },
  "description": "Programming language"
}

Create a Dart class to represent this summary.

1. Create the directory wikipedia/lib/src/model.

   bash

   mkdir -p wikipedia/lib/src/model
   

   content_copy

2. Create the file wikipedia/lib/src/model/summary.dart.

3. Add the following code to wikipedia/lib/src/model/summary.dart:

   wikipedia/lib/src/model/summary.dart

   dart

   import 'title_set.dart';
   ​
   class Summary {
     /// Returns a new [Summary] instance.
     Summary({
       required this.titles,
       required this.pageid,
       required this.extract,
       required this.extractHtml,
       required this.lang,
       required this.dir,
       this.url,
       this.description,
     });
   ​
     ///
     TitlesSet titles;
   ​
     /// The page ID
     int pageid;
   ​
     /// First several sentences of an article in plain text
     String extract;
   ​
     /// First several sentences of an article in simple HTML format
     String extractHtml;
   ​
     /// Url to the article on Wikipedia
     String? url;
   ​
     /// The page language code
     String lang;
   ​
     /// The page language direction code
     String dir;
   ​
     /// Wikidata description for the page
     String? description;
   ​
     /// Creates a [Summary] instance from a JSON map.
     factory Summary.fromJson(Map<String, Object?> json) {
       return switch (json) {
         {
           'titles': final Map<String, Object?> titles,
           'pageid': final int pageid,
           'extract': final String extract,
           'extract_html': final String extractHtml,
           'lang': final String lang,
           'dir': final String dir,
           'content_urls': {
             'desktop': {'page': final String url},
             'mobile': {'page': String _},
           },
           'description': final String description,
         } =>
           Summary(
             titles: TitlesSet.fromJson(titles),
             pageid: pageid,
             extract: extract,
             extractHtml: extractHtml,
             lang: lang,
             dir: dir,
             url: url,
             description: description,
           ),
         {
           'titles': final Map<String, Object?> titles,
           'pageid': final int pageid,
           'extract': final String extract,
           'extract_html': final String extractHtml,
           'lang': final String lang,
           'dir': final String dir,
           'content_urls': {
             'desktop': {'page': final String url},
             'mobile': {'page': String _},
           },
         } =>
           Summary(
             titles: TitlesSet.fromJson(titles),
             pageid: pageid,
             extract: extract,
             extractHtml: extractHtml,
             lang: lang,
             dir: dir,
             url: url,
           ),
         _ => throw FormatException('Could not deserialize Summary, json=$json'),
       };
     }
   ​
     @override
     String toString() =>
         'Summary['
         'titles=$titles, '
         'pageid=$pageid, '
         'extract=$extract, '
         'extractHtml=$extractHtml, '
         'lang=$lang, '
         'dir=$dir, '
         'description=$description'
         ']';
   }
   

   content_copy

   This code defines a Summary class to represent the fields returned by the Wikipedia summary endpoint:

   • fromJson pattern matching: While you can access map keys individually with manual casting (such as json['pageid'] as int), the fromJson factory constructor uses pattern matching to validate the structure, confirm types, and extract values in a single declarative expression.
   • switch expression: Provides two cases to handle Wikipedia's optional description field: one that extracts it when present, and a fallback case that matches when it is omitted.
   • toString: Provides a readable string representation of the Summary object for debugging.

The Summary class uses a TitlesSet class to represent the title information. Create that class next.

1. Create the file wikipedia/lib/src/model/title_set.dart.

2. Add the following code to wikipedia/lib/src/model/title_set.dart:

   wikipedia/lib/src/model/title_set.dart

   dart

   class TitlesSet {
     /// Returns a new [TitlesSet] instance.
     TitlesSet({
       required this.canonical,
       required this.normalized,
       required this.display,
     });
   ​
     /// the DB key (non-prefixed), e.g. may have _ instead of spaces,
     /// best for making request URIs, still requires Percent-encoding
     String canonical;
   ​
     /// the normalized title (https://www.mediawiki.org/wiki/API:Query#Example_2:_Title_normalization),
     /// e.g. may have spaces instead of _
     String normalized;
   ​
     /// the title as it should be displayed to the user
     String display;
   ​
     /// Creates a [TitlesSet] instance from a JSON map.
     factory TitlesSet.fromJson(Map<String, Object?> json) {
       if (json case {
         'canonical': final String canonical,
         'normalized': final String normalized,
         'display': final String display,
       }) {
         return TitlesSet(
           canonical: canonical,
           normalized: normalized,
           display: display,
         );
       }
       throw FormatException('Could not deserialize TitleSet, json=$json');
     }
   ​
     @override
     String toString() =>
         'TitlesSet['
         'canonical=$canonical, '
         'normalized=$normalized, '
         'display=$display'
         ']';
   }
   

   content_copy

   This code defines a TitlesSet class to hold the title variants returned by the Wikipedia API. Unlike Summary, which uses a switch expression for optional fields, TitlesSet has a fixed structure and validates all three fields at once using an if case statement. If the JSON map does not match the pattern, it throws a FormatException.

The Wikipedia API also returns a list of articles in a search result. Create a Dart class to represent an article.

1. Create the file wikipedia/lib/src/model/article.dart.

2. Add the following code to wikipedia/lib/src/model/article.dart:

   wikipedia/lib/src/model/article.dart

   dart

   class Article {
     Article({required this.title, required this.extract});
   ​
     final String title;
     final String extract;
   ​
     static List<Article> listFromJson(Map<String, Object?> json) {
       final List<Article> articles = <Article>[];
       if (json case {'query': {'pages': final Map<String, Object?> pages}}) {
         for (final MapEntry<String, Object?>(:Object? value) in pages.entries) {
           if (value case {
             'title': final String title,
             'extract': final String extract,
           }) {
             articles.add(Article(title: title, extract: extract));
           }
         }
         return articles;
       }
       throw FormatException('Could not deserialize Article, json=$json');
     }
   ​
     Map<String, Object?> toJson() => <String, Object?>{
       'title': title,
       'extract': extract,
     };
   ​
     @override
     String toString() {
       return 'Article{title: $title, extract: $extract}';
     }
   }
   

   content_copy

   This code defines an Article class to represent an article's title and extract:

   • listFromJson: Unlike previous models that create a single instance, the Wikipedia search endpoint returns multiple articles in a map. Dart constructors only return a single instance, so Article uses a static method named listFromJson to return a List<Article>.
   • Object pattern destructuring: The for loop uses final MapEntry(:value) to extract each entry's value directly without manual property access.
   • toJson: Converts an Article instance back into a JSON map. In Dart convention, toJson() returns a Map<String, Object?> that you can pass to jsonEncode() from dart:convert when serializing an object to a JSON string.

Finally, create a class to represent search results from the Wikipedia API. The Wikipedia search endpoint returns an array containing the search term, article titles, descriptions (which are ignored), and URLs:

[
  "dart",
  ["Dart (programming language)", "Dart"],
  ["", ""],
  [
    "https://en.wikipedia.org/wiki/Dart_(programming_language)",
    "https://en.wikipedia.org/wiki/Dart"
  ]
]

1. Create the file wikipedia/lib/src/model/search_results.dart.

2. Add the following code to wikipedia/lib/src/model/search_results.dart:

   wikipedia/lib/src/model/search_results.dart

   dart

   class SearchResult {
     SearchResult({required this.title, required this.url});
     final String title;
     final String url;
   }
   ​
   class SearchResults {
     SearchResults(this.results, {this.searchTerm});
     final List<SearchResult> results;
     final String? searchTerm;
   ​
     /// Creates a [SearchResults] instance from a JSON list.
     factory SearchResults.fromJson(List<Object?> json) {
       final List<SearchResult> results = <SearchResult>[];
       if (json case [
         String searchTerm,
         Iterable articleTitles,
         Iterable _,
         Iterable urls,
       ]) {
         final List titlesList = articleTitles.toList();
         final List urlList = urls.toList();
         for (int i = 0; i < articleTitles.length; i++) {
           results.add(SearchResult(title: titlesList[i], url: urlList[i]));
         }
         return SearchResults(results, searchTerm: searchTerm);
       }
       throw FormatException('Could not deserialize SearchResults, json=$json');
     }
   ​
     @override
     String toString() {
       final StringBuffer pretty = StringBuffer();
       for (final SearchResult result in results) {
         pretty.write('${result.url} \n');
       }
       return '\nSearchResults for $searchTerm: \n$pretty';
     }
   }
   

   content_copy

   This code defines two classes: SearchResult to hold an individual article's title and URL, and SearchResults to hold the list of results along with the search query:

   • fromJson with List<Object?>: The constructor accepts a List<Object?> rather than a Map<String, Object?> to match the top-level JSON array returned by Wikipedia's search API.
   • List pattern matching: The if case statement uses a list pattern [...] to match the array positionally and extract each section.
   • Wildcard pattern (_): The Iterable _ pattern matches and discards the descriptions array, which your application does not need.

You now have typed data models to represent Wikipedia API responses. In upcoming chapters, use package:test to test how data is deserialized and use package:http to fetch live JSON data from the API.

In the next lesson, learn how to test your Dart code using the package:test library. Write tests to verify that your JSON deserialization logic works correctly.