Developer Migration Docs - Ghost Developer Docs

JSON file structure

First and foremost, your JSON file must contain valid JSON. You can test your file is valid using the JSONLint online tool. The file structure can optionally be wrapped in:

{
  "db": [...contents here...]
}

Both with and without are valid Ghost JSON files. But you must include a meta and a data object.

The meta object

"meta": {
    "exported_on": 1753891082041,
    "version": "6.0.0"
}

The meta block expects two keys, exported_on and version. exported_on should be an epoch timestamp in milliseconds, version should be the Ghost version the import is valid for.

The data block

Ghost’s JSON format mirrors the underlying database structure, rather than the API, as it allows you to override fields that the API would ignore.

"data": {
  "posts": [{...}, ...],
  "posts_meta": [{...}, ...],
  "tags": [],
  "posts_tags": [],
  "users": [],
  "posts_authors": []
}

The data block contains all of the individual post, tag, and user resources that you want to import into your site, as well as the relationships between all of these resources. Each item that you include should be an array of objects. Relationships can be defined between posts and tags, posts and users (authors). IDs inside the file are relative to the file only, so if you have a post with id: "1234" and a posts_tags object which references post_id: "1234", then those two things will be linked, but they do not relate to the post with id: "1234" in your database. The example below is a working but simplified to cover most use-cases. To see what fields are available, types, lengths, and validations, please refer to the Ghost schema on GitHub.

Example

{
    "meta": {
        "exported_on": 1753891082041,
        "version":     "6.0.0" // Ghost version the import is valid for
    },
    "data": {
        "posts": [
            {
                "id":             "1234", // The post ID, which is refered to in other places in this file
                "title":          "My Blog Post Title",
                "slug":           "my-blog-post-title",
                "html":           "<p>Hello world, this is an article</p>", // You could use `lexical` instead to to represent your content
                "comment_id":     "1234-old-cms-post-id", // The ID from the old CMS, which can be output in the theme
                "feature_image":  "/content/images/2024/waving.jpg",
                "type":           "post", // post | page
                "status":         "published", // published | draft
                "visibility":     "public", // public | members | paid
                "created_at":     "2025-06-30 15:31:36",
                "updated_at":     "2025-07-02 08:22:14",
                "published_at":   "2025-06-30 15:35:36",
                "custom_excerpt": "My custom excerpt"
            }
        ],
        // Optionally define post metadata
        "posts_meta": [
            {
                "post_id":               "1234", // This must be the same as the post it references
                "feature_image_alt":     "A group of people waving at the camera",
                "feature_image_caption": "The team says hello!"
            }
        ],
        // Define the tags
        "tags": [
            {
                "id":   "3456", // Unique ID for this tag
                "name": "News & Weather",
                "slug": "news-weather"
            }
        ],
        // Relate posts to tags
        "posts_tags": [
            {
                "post_id": "1234", // The post ID from the `posts` array
                "tag_id":  "3456" // The tag ID from the `tags` array
            }
        ],
        // Define the users
        "users": [
            {
                "id":            "5678", // Unique ID for this author
                "name":          "Jo Bloggs",
                "slug":          "jo-blogs",
                "email":         "jo@example.com",
                "profile_image": "/content/images/2025/scenic-background.jpg",
                "roles": [
                    "Contributor" // Contributor | Author| Editor | Administrator
                ]
            }
        ],
        // Relate posts to authors
        "posts_authors": [
            {
                "post_id":   "1234", // The post ID from the `posts` array
                "author_id": "5678" // The author ID from the `users` array
            }
        ]
    }
}

​JSON file structure

​The meta object

​The data block

​Example

JSON file structure

The meta object

The data block

Example