JSON Import Format Specification

General Information

SnippetsLab defines a JSON library format, described below, as the recommended intermediate format for importing data from any source that SnippetsLab doesn’t support directly.

The format covers most of the app’s features, and a file can use only the subset it needs. For example, a JSON file can contain only snippets, without folders or tags. Most attributes are optional, with a few exceptions that are marked Required in the description. If a required attribute is missing, the import fails with an error. The exceptions are a tag without a title and a smart group without a predicate, which are skipped. Attachments aren’t imported from JSON files.

The easiest way to see the format is to export a small library. Choose Library > Export, choose JSON Document from the Format pop-up menu, and use the exported file as a template. Exported files contain some additional keys that aren’t listed below. They aren’t needed for import.

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, which are the items in Favorites in the sidebar.

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.
`defaultLanguage`	String	Default language for new snippets in this folder, as a lexer class name such as `PythonLexer`. For how default languages work, see Default Language.

Snippet

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

Field	Type	Description
`title`	String	Name of the snippet. Required.
`uuid`	String	Unique identifier. See discussion.
`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.
`locked`	Boolean	Indicates whether this snippet is locked for editing.
`dateCreated`	String	Creation date of the snippet. See discussion.
`dateModified`	String	Last modification date of the snippet. See discussion.
`dateDeleted`	String	Date the snippet was moved to the Trash. If present, the snippet is imported into the Trash. See discussion.
`fragments`	`[Fragment]`	An array of fragments. Each snippet 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.
`uuid`	String	Unique identifier. See discussion.
`note`	String	Text for the notes area.
`noteAttributes`	`[NoteAttribute]`	Rich text attributes for the notes.
`content`	String	The content of the fragment. 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. Required.
`uuid`	String	Unique identifier. See discussion. Required.
`accentColor`	Integer	Color of the tag: `1` red, `2` green, `3` blue, `4` orange, `5` yellow, `6` brown, `7` pink, `8` purple, `9` gray, `11` indigo, `12` mint, or `13` cyan. Omit it for no color.

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: `strong`, `italic`, `underline`, `code`, `mark`, `strikethrough`, `subscript`, `superscript`, or `link`. Any other name causes the import to fail. Required.
`range`	`[Integer]`	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, used only for the `link` attribute, where it contains the target URL.

Discussion

UUID: In the JSON format, UUIDs are used for cross-references between entities. For example, each folder must have a uuid, and every snippet in the folder refers to the folder by that value. Similarly, a shortcut refers to its target folder, smart group, or tag by its UUID. The UUIDs don’t have to conform to any specific format, but they must be unique across all UUIDs in the JSON file.

References that don’t match are dropped without an error. A snippet whose folder isn’t found is imported into Uncategorized, tag UUIDs that aren’t found are removed from the snippet, and a shortcut whose target isn’t found is skipped.

Snippet and fragment UUIDs are kept only when you import a file exported from SnippetsLab, so that links to those snippets keep working. Otherwise, SnippetsLab assigns new UUIDs.
Date: All dates, such as dateCreated and dateModified, are formatted as strings that conform to the ISO 8601 standard, with a date, a time, and a time zone, such as 2011-08-29T20:34:41Z. Fractional seconds aren’t supported. The import fails if any date can’t be read.
Language: In a fragment, the language is a Pygments lexer class name, such as PythonLexer. For the class names, see the Pygments documentation. SnippetsLab may not support all languages listed there.

If the value isn’t a lexer class name, or if there is no value, SnippetsLab guesses the language using the following heuristics, in order:
1. A shebang in the first line of the content, such as #!/usr/bin/env python3
2. A mode line in the first line of the content, such as -*- mode: python -*-
3. A first line that identifies the language, such as <?xml or <?php (only for some languages)
4. A language value that matches a Pygments short name or display name
5. Plain Text, if none of the above applies
Predicate: Each smartGroup must have a predicate attribute that defines the search criteria. The value uses the NSPredicate format string syntax.

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"
      }
    ]
  }
}