Skip to content
Unlock seamless workflows and faster delivery with our latest releases - Join the deep dive
Get help on Slack

Understanding the JSON format for importing PortableText into Sanity

20 replies
Last updated: Jul 5, 2022
Looking for any resources/examples about the JSON format needed to handle importing PortableText.
I’m using the Sanity CLI to import content (for the first time) and was surprised not to find anything in snippets, docs, StackOverflow, Googling, etc. I assume this one of the main challenges anyone faces when getting data into Sanity.
Jun 30, 2022, 11:53 PM
This is the closest thing I could think of:
Deserialization and the
relevant GitHub -- it's not a direct correlation but since there are likely analogues in your objects, it could be a useful middle ground.
Jul 1, 2022, 12:05 AM
This was my shot at just trying to surf the errors to get any text in at all.

  "excerpt": {
    "_type": "block",
    "children": [
      {
        "_type": "span",
        "text": "My text here."
      }
    ]
  },
Jul 1, 2022, 12:08 AM
But I wind up with 
TypeError: val is not iterable
after the import runs successfully.
Jul 1, 2022, 12:09 AM
I’m still missing the layer of my PortableText object type, but it’s unclear what property the value is stored in.
Jul 1, 2022, 12:11 AM
It should be something like…


  "excerpt": {
    "_type": "strictPortableText",
    "blocks": [
      {
        "_type": "block",
        "children": [
          {
            "_type": "span",
            "text": "Learn how to deliver impactful DevRel campaigns that drive results and impress stakeholders."
          }
        ]
      }
    ]
  }
Jul 1, 2022, 12:14 AM
Just to be clear, you have outside existing JSON, and you want to run that through a process to become portable text, so you can form a document using that result as the portable text for that document?
If I am underestanding correctly, the result should be an array that looks like this example:
https://www.sanity.io/guides/introduction-to-portable-text#24a5ca89c31c but the array itself would be placed inside a label corresponding to the field you've chosen to be the block editor / array of blocks:
(reproducing from a little lower from that same link because there's no direct link)


{
  "body": [
    {
      "_type": "block",
      "style": "normal",
      "children": [
        {
          "_type": "span",
          "marks": [],
          "text":  "You can visit us in our opening hours at this location:"
        }
      ],
      "markDefs": []
    },
    {
      "_type": "location",
      "coordinates": {
        "_type": "geopoint",
        "lat": 59.924010,
        "long": 10.758880
      }
    }
  ]
}
Jul 1, 2022, 12:17 AM
Sit tight for a sec and I will get an example from one of my actual documents so you can see it in context.
Jul 1, 2022, 12:18 AM
It seems like I have to name the portable text type or the admin UI complains. Something like…

  "excerpt": {
    "_type": "strictPortableText",
    "children": [
      {
        "_type": "block",
        "children": [
          {
            "_type": "span",
            "text": "Learn how to deliver impactful DevRel campaigns that drive results and impress stakeholders."
          }
        ]
      }
    ]
  },
Jul 1, 2022, 12:19 AM
Here's one of my documents that has two Portable Text fields -- note the first, additionalInformation, starting on line 7 and the second, placeBody on line 46 (apologies for lack of color highlighting)
Jul 1, 2022, 12:22 AM
This did the trick…
  "excerpt": [
    {
      "_type": "block",
      "style": "normal",
      "children": [
        {
          "_type": "span",
          "text": "Learn how to deliver impactful DevRel campaigns that drive results and impress stakeholders.",
          "marks": []
        }
      ],
      "markDefs": []
    }
  ],
Jul 1, 2022, 12:22 AM
Great! Yeah it's kind of like a reverse math problem to check the answer. You might not use the Studio at all but if it has to run the doc against a schema to interpret it to view, it needs something to hang it on like that.
Jul 1, 2022, 12:23 AM
BTW: This is the wrong/misleading help text…
Jul 1, 2022, 12:23 AM
OMG, I just found the “INSPECT” button!
Jul 1, 2022, 12:29 AM
I am just a random person and don't work for Sanity so I can't really account for anything except what I've experienced and I've never done an import like you're talking about. I haven't even programmatically created a document yet.
Jul 1, 2022, 12:29 AM
Oh yeah haha Inspect is what I used to make the link to my doc I sent a few mins ago
Jul 1, 2022, 12:30 AM
🤯
Jul 1, 2022, 12:31 AM
Thank you random Vincent!
Jul 1, 2022, 12:31 AM
haha I am not sure of the process, specific Josh, but I noticed in the resulting format and what you had earlier, the individual blocks in the array you had were missing keys. The GitHub tool I linked earlier might be generating those.

Notice that this example includes a _key. This is included to make it easier to use Portable Text in real-time interfaces. However, we will omit it in the following code examples for readability.
I think it's particularly so that if you're collaborating people can't be working on the same parts of the block editor and overwriting each other.
Jul 1, 2022, 12:34 AM
Gotcha. I assumed Sanity would autogenerate a 
_key
on the way in during the import. I’d better confirm.
Jul 5, 2022, 6:17 PM
It's definitely a good question, I just don't know the answer outright.
Jul 5, 2022, 7:05 PM

Sanity– build remarkable experiences at scale

Sanity is a modern headless CMS that treats content as data to power your digital business. Free to get started, and pay-as-you-go on all plans.

Get started for freeExplore the demo

Was this answer helpful?