What's the proper JSON-LD Syntax for an Array of Objects?

Question

The app I'm developing has an API to fetch a single object that I describe in JSON-LD like so:

{
  "@context": {
    "@vocab": "https://schema.org/",
    "head": "@nest",
    "id": { "@id": "identifier" },
    "type": { "@id": "name" },
    "created_at": { "@id": "dateCreated" },
    "updated_at": { "@id": "dateModified" },
    "created_by": { "@id": "name" },
    "updated_by": { "@id": "name" },
    "body": { "@type": "@json", "@id": "_:body" }
  }
}

This works well in the Link header for a response containing a single object like:

{
  "head": {
    "id": "29a28e6a-6ef9-46bd-8981-f929486821cb",
    "type": "widget",
    "created_by": "theory",
    "created_at": "2024-04-26T01:29:49.542Z",
    "updated_by": "julie",
    "updated_at": "2025-04-23T15:14:51.053Z"
  },
  "body": {
    "username": "Alexandra",
    "active": true,
    "age": 32
  }
}

But I also have a search API that returns an array of objects, all of which comply with this @context. What's the proper JSON-LD incantation usable in a link header to represent an array of objects with the same context as for this single object?

Oluwafemi Sule · Accepted Answer · 2025-07-23 15:47:55Z

2

When using HTTP Link Header to reference a JSON-LD context document in an HTTP Link Header, the docs say that

If an array is at the top-level of the referencing document and its items are JSON objects, the @context subtree is added to all array items.

Where the JSON-LD context document is referenced in the response content rather than in the HTTP Link Header, modify each array entry to include the @context if the published endpoint that returns the array is already being used by consumers to avoid breaking their applications. Make sure to publish your context definition to a URL accessible to JSON-LD processors.

[
  {
    "@context": "<replace with URL for context definition>",
    "head": {
      "id": "d7cf7ea4-3f57-47b6-b9ff-2068fce3a91f",
      "type": "widget",
      "created_by": "emil",
      "created_at": "2024-05-13T09:16:00.000Z",
      "updated_by": "emil",
      "updated_at": "2025-06-01T12:00:00.000Z"
    },
    "body": {
      "username": "Bruno",
      "active": false,
      "age": 29
    }
  }
]

If you still have control over the structure of the response such that consumers of the API endpoint can also be modified, you can convert it into an object and use @graph property to provide the array of individual objects.

{
  "@context": "<inline context definition or replace with URL for context definition>",
  "@graph": [
    {
      "head": {
        "id": "29a28e6a-6ef9-46bd-8981-f929486821cb",
        "type": "widget",
        "created_by": "theory",
        "created_at": "2024-04-26T01:29:49.542Z",
        "updated_by": "julie",
        "updated_at": "2025-04-23T15:14:51.053Z"
      },
      "body": {
        "username": "Alexandra",
        "active": true,
        "age": 32
      }
    }
  ]
}

edited Jul 23 at 15:47

answered Jul 23 at 11:46

Oluwafemi Sule

39.3k1 gold badge63 silver badges88 bronze badges

Sign up to request clarification or add additional context in comments.

4 Comments

theory Jul 23 at 14:06

I should have said: I'm not embedding the context into objects but want to link to it in the Link header. All the objects in the array are of the same type.

theory Jul 23 at 14:20

I've updated the question with that…context.

Oluwafemi Sule Jul 23 at 15:58

When using the Link header, you don't have to make any extra steps. A parser like Rdflib will build your graph.

theory Jul 23 at 18:18

Ooooh, somehow I missed the meaning of that bit of the docs when I read it. I see now that the JSON-LD example in my question can be used for either a response with a single object or for all the objects in an array of objects in a response. Easier than I thought!

Collectives™ on Stack Overflow

What's the proper JSON-LD Syntax for an Array of Objects?

1 Answer 1

4 Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

4 Comments

Your Answer

Sign up or log in

Post as a guest

Related