Documentation Archive


Playground Book Format Reference

On This Page

Creating Subscriptions

If you're writing episodic content in your Swift Playgrounds learning material, or want to space out the releases of your lessons over time, you can build a subscription that guides people through your lessons one by one. This chapter describes the process of creating and hosting the subscription data you need to start publishing your playgrounds so people can subscribe to them in Swift Playgrounds.

Understanding Subscriptions

Swift Playgrounds subscriptions live on the Internet as feeds. Like podcasts, subscriptions in Swift Playgrounds are a sequence of episodic content learners go through in an order that builds knowledge, though some parts may be skippable depending on the learner.

A feed is a downloadable list of items that apps and websites understand. The feed for your subscription is a way for you publish a set of playgrounds that the Swift Playgrounds app knows how to download, process, and display. Feeds in Swift Playgrounds are structured in a text format called JSON.

Understanding Feeds and JSON

JSON is a textual data format that many apps and websites use to communicate and share information. It consists primarily of lists, definition lists, and raw values like strings and numbers. You use it to build up a feed for your subscription.

A simple—yet complete—JSON document looks like this:

  1. {
  2. "bookTitle": "Whimsical Swift Syntax",
  3. "publishDate": 2017,
  4. "simpleList": ["one", 1, "two", 2]
  5. }

The example document isn't detailed enough to be a real feed for a playground subscription, but it illustrates the kind of information a feed contains. The JSON you'll see used by apps is typically longer, but those longer JSON documents follow the same rules of quoting and nesting. For more information about JSON, see ECMA-404: The JSON Data Interchange Format.

Not all JSON documents are feeds. Feeds of JSON are informally defined by two characteristics:

  1. They consist of metadata, like "What's the name of this feed?", and a primary list of homogeneous data items.

  2. They link to, but do not contain, some media of interest (such as a link to an audio file, a blog post, or a playground).

The feed format used by Swift Playgrounds meets these two characteristics: feeds have some details (metadata) used to name, describe, and identify the subscription; feeds also contain a link to each individual playground book in a subscription.

Update a Subscription by Adding Items to Its Feed

When you hear something is a subscription, you expect it to be updated over time. The same expectation applies to the feeds distributing your playground subscriptions. Adding, removing, or updating the subscription involves two steps: creating a new or updated playground book, then adjusting the JSON feed so it corresponds to the updates you've just made.

When you update a playground book, be sure to update the JSON feed that links to the book at the same time. If the feed is out of date, there may be a mismatch between the preview information contained in the feed and the content in the playground books the feed links to.

An Example Subscription Feed

This example shows a feed with two playground books that make up the whole series. For detailed information about the feed format, see Subscription Feed Format.

  1. {
  2. "title": "Whimsical Swift Syntax",
  3. "subtitle": "A Collection of Swift Lessons",
  4. "publisherName": "Company Name Inc.",
  5. "feedIdentifier": "com.example.whimsicalswift",
  6. "contactURL": "",
  7. "formatVersion": "1.0",
  8. "documents": [
  9. {
  10. "title": "The Key Path Not Taken",
  11. "overviewSubtitle": "Dynamically Choosing Among Key Paths",
  12. "detailSubtitle": "Because key paths in Swift are applied at runtime, their behavior is dynamic.",
  13. "description": "Learn to compare key paths and pick the right one.",
  14. "contentIdentifier": "com.example.whimsicalswift.keypaths",
  15. "contentVersion": "1.0",
  16. "url": "keypaths/",
  17. "publishedDate": "2017-11-13T21:13:57+00:00",
  18. "lastUpdatedDate": "2017-11-13T21:13:57+00:00",
  19. "thumbnailURL": "keypaths/thumbnail.png",
  20. "bannerImageURL": "keypaths/banner.png",
  21. "additionalInformation": [
  22. {
  23. "name": "Languages",
  24. "value": "English"
  25. }
  26. ],
  27. "previewImageURLs": [
  28. "keypaths/preview-1.png"
  29. ]
  30. },
  31. {
  32. "title": "Structer Things",
  33. "overviewSubtitle": "Understand Structures by Comparing Them with Classes",
  34. "detailSubtitle": "Choose between using a structure or a class to model data.",
  35. "description": "Learn about value semantics and reference semantics.",
  36. "contentIdentifier": "com.example.whimsicalswift.structures-and-classes",
  37. "contentVersion": "1.0",
  38. "url": "structures-and-classes/",
  39. "publishedDate": "2017-11-13T21:13:57+00:00",
  40. "lastUpdatedDate": "2017-11-13T21:13:57+00:00",
  41. "thumbnailURL": "structures-and-classes/thumbnail.png",
  42. "bannerImageURL": "structures-and-classes/banner.png",
  43. "additionalInformation": [
  44. {
  45. "name": "Languages",
  46. "value": "English"
  47. }
  48. ],
  49. "previewImageURLs": [
  50. "structures-and-classes/preview-1.png"
  51. ]
  52. }
  53. ]
  54. }