Get help on Discord

Dataset Import - How to Format the Ndjson File for References

4 replies
Last updated: Aug 16, 2022
hi all! working on a dataset import right now and trying to figure out how to format my 
ndjson
file to account for references.
this is part of the schema i’m importing into, specifically wondering how I should format for the 
pressLinks
field

...
        {
            name: 'pressLinks',
            title: 'Selected Press',
            type: 'array',
            of: [{ type: 'pressLinks' }],
            group: 'press',
        },
...
AI Update

When formatting your NDJSON file to handle references, you need to structure them differently depending on whether you're dealing with regular document references or asset references.

For your pressLinks field (which appears to be an array of references to other documents), here's how to format it in your NDJSON:

For document references:

Each line in your NDJSON should look like this:

{"_id": "your-document-id", "_type": "yourType", "pressLinks": [{"_type": "reference", "_ref": "id-of-pressLink-document-1", "_key": "unique-key-1"}, {"_type": "reference", "_ref": "id-of-pressLink-document-2", "_key": "unique-key-2"}]}

The key parts are:

  • _type: "reference" (required for reference fields)
  • _ref: The _id of the document you're referencing
  • _key: A unique identifier for each array item (optional but recommended)

Important note about weak references during import:

During import, Sanity automatically converts all references to weak references first, then strengthens them after all documents are in place. This means you can import documents in any order without worrying about reference order. However, if you want to keep them as weak references permanently, you'd set "_weak": true in your reference object.

If your pressLinks contain asset references (images/files):

Use the special _sanityAsset property instead:

{"_id": "your-document-id", "_type": "yourType", "pressLinks": [{"_type": "image", "_sanityAsset": "image@https://example.com/image.jpg"}]}

The format is image@ or file@ followed by either a URL or a file path like file:///absolute/path/to/file.jpg.

Pro tip: Make sure your NDJSON is properly formatted with one complete JSON object per line (no pretty printing or line breaks within objects). The CLI import command handles references automatically, converting them from weak to strong after all documents are imported, which is why order doesn't matter!

Hey
user E
! Are presslinks objects or references?
they are objects, here is the schema

export default {
    name: 'pressLinks',
    title: 'Press Links',
    type: 'object',
    fields: [
        {
            name: 'title',
            title: 'Press Outlet Name',
            type: 'string',
        }, {
            name: 'url',
            title: 'Press Link URL',
            type: 'url',
        }
    ],
}
Got it! I wasn't sure because of this:
trying to figure out how to format my 
ndjson
file to account for references.
For presslinks, they would need to be in this format.
{
 //...other fields
  pressLinks: [
    {
       _type: 'pressLink',
       title: <your-title>,
       url: <your-url
    },
    //...other pressLinks
  ]
}
user M
perfect thank you so much! was just missing the 
_type
property 🙂

Sanity – Build the way you think, not the way your CMS thinks

Sanity is the developer-first content operating system that gives you complete control. Schema-as-code, GROQ queries, and real-time APIs mean no more workarounds or waiting for deployments. Free to start, scale as you grow.

Get started for freeExplore the demo

Was this answer helpful?