JSON Import Format Specification

General information

SnippetsLab defines a JSON library format and can import data from any .json file that conforms to the required format, as discussed below. This makes it possible to import from arbitrary third-party sources as long as they are converted to the supported format first.

The JSON format is designed to support the app’s full feature set while allowing users to use only a subset of them. For example, you can generate and import a JSON file that only contains snippets (no folders, tags, etc.). Most of the attributes are optional, with a few exceptions, which are marked as “required” in the description.

Schema

Root

Key path: (root)

Field	Type	Description
`contents`	Dictionary	A dictionary containing all folders, snippets, smart groups, tags, and shortcuts. Required.

Contents

Key path: (root).contents

Field	Type	Description
`folders`	`[Folder]`	An array of all root level folders.
`snippets`	`[Snippet]`	An array of all snippets.
`smartGroups`	`[SmartGroup]`	An array of all smart groups.
`tags`	`[Tag]`	An array of all tags.
`shortcuts`	`[Shortcut]`	An array of all shortcuts.

Folder

Key path: (root).contents.folders[*].

Field	Type	Description
`title`	String	Name of the folder.
`uuid`	String	Unique identifier. See discussion. Required.
`children`	`[Folder]`	An array of subfolders inside the folder.

Snippet

Key path: (root).contents.snippets[*].

Field	Type	Description
`title`	String	Name of the snippet. Required.
`folder`	String	UUID of the folder that this snippet belongs to.
`tags`	`[String]`	An array of UUIDs of tags assigned to this snippet.
`pinned`	Boolean	Indicates whether this snippet is pinned.
`dateCreated`	String	Creation date of the snippet. See discussion.
`dateModified`	String	Last modification date of the snippet. See discussion.
`fragments`	`[Fragment]`	An array of `fragments`. Each must have at least one fragment. Required.

Fragment

Key path: (root).contents.snippets[*].fragments[*].

Field	Type	Description
`title`	String	Name of the fragment, this is often omitted if there is only one fragment.
`note`	String	Text for the notes area.
`noteAttributes`	`[NotesAttribute]`	Rich text attributes for the notes.
`content`	String	The content of the snippet. Required.
`language`	String	Language of the fragment. See discussion.
`dateCreated`	String	Creation date of the fragment. See discussion.
`dateModified`	String	Last modification date of the fragment. See discussion.

Smart Group

Key path: (root).contents.smartGroups[*].

Field	Type	Description
`title`	String	Name of the smart group.
`uuid`	String	Unique identifier. See discussion. Required.
`predicate`	String	Search predicate of the smart group. See discussion. Required.

Tag

Key path: (root).contents.tags[*].

Field	Type	Description
`title`	String	Name of the tag.
`uuid`	String	Unique identifier. See discussion. Required.

Shortcut

Key path: (root).contents.shortcuts[*].

Field	Type	Description
`uuid`	String	Unique identifier of the folder, smart group or tag that this shortcut links to. Required.

Note Attribute

Key path: (root).contents.snippets[*].fragments[*].noteAttributes[*].

Field	Type	Description
`name`	String	Name of the attribute, for example `strong`, `underline`, `link`, etc. Required.
`range`	[Int]	Range of this attribute, in the format of `[location, length]`. The offsets are measured in UTF-16 code units. Required.
`stringValue`	String	An optional string value for the attribute, currently only used for the `link` attribute, where this should be the URL for the link.

Discussion

UUID: In the JSON format, UUIDs are used for cross-referencing between entities. For example, each folder must have a uuid, whose value is then referenced by all snippet located within the folder. Similarly, a shortcut references the target folder, smart group, or tag with their UUID. The UUIDs do not have to conform to any specific format, but they must be unique across all UUIDs in the JSON file.
Date: All dates, such as dateCreated and dateModified, are formatted as strings that conform to the ISO 8601 standard. For example, 2011-08-29T20:34:41Z.
Language: In a fragment, the language is expressed by a Pygments lexer name. See Pygments documentation for a complete list. Note that some languages listed there may not be supported by SnippetsLab.
Predicate: Each smartGroup must have a predicate attribute indicating the search criteria. This predicate is used by NSPredicate internally.

Example

{
  "contents": {
    "folders": [
      {
        "title": "Publishing",
        "uuid": "D3F0277B-6230-46C1-9D2E-3E1B8CE509BF"
      },
      {
        "title": "Graphic Design",
        "uuid": "D42BB115-44C4-4931-ACF8-8AD5F2D1778C",
        "children": [
          {
            "title": "Subfolder 1",
            "uuid": "4D356EC0-6118-4DDE-B09C-EC4116698877",
          },
          {
            "title": "Subfolder 2",
            "uuid": "2C6E47F2-A23F-4B4D-B63E-B1C37973A7BC",
          }
        ]
      }
    ],
    "snippets": [
      {
        "title": "Lorem ipsum",
        "folder": "D3F0277B-6230-46C1-9D2E-3E1B8CE509BF",
        "fragments": [
          {
            "title" : "Fragment",
            "language": "MarkdownLexer",
            "note": "Lorem ipsum is a placeholder text commonly used to demonstrate the visual form of a document or a typeface without relying on meaningful content.",
            "content": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.",
            "dateCreated": "2011-08-29T20:34:41Z",
            "dateModified": "2011-08-29T20:34:41Z",
            "uuid": "FA7BA77B-A93C-4D92-AC70-42EFF051C4D5",
          }
        ],
        "tags": [
          "017B7917-6B0A-4E9C-8757-F142E7B3C615",
          "D292ECB1-F007-4CE7-A65C-4AB08AD689FD"
        ],
        "dateCreated": "2011-08-29T20:34:41Z",
        "dateModified": "2011-08-29T20:34:41Z",
        "uuid": "5E680391-9BB0-4C8F-BC52-39F1836A717F",
      }
    ],
    "smartGroups": [
      {
        "title": "Markdown",
        "predicate": "ANY parts.language.displayName ==[cd] \"Markdown\"",
        "uuid": "41AD5A0A-84DE-4CD8-A951-7ED4060F7476",
      },
    ],
    "tags": [
      {
        "title": "lorem",
        "uuid": "017B7917-6B0A-4E9C-8757-F142E7B3C615",
      },
      {
        "title": "ipsum",
        "uuid": "D292ECB1-F007-4CE7-A65C-4AB08AD689FD",
      }
    ]
  }
}