Recommendation for included objects?

[davidbarratt]

Given a response object like:

{
	"@context": "https://schema.org",
	"type": "Collection",
	"hasPart": [
	    {
			"id": "123",
			"type": "ScreeningEvent",
			"location": "abc"
		},
		{
			"id": "456",
			"type": "ScreeningEvent",
			"location": "abc"
		}
	]
}

where the Collection is a collection of objects of type ScreeningEvent, should the response include the abc object?

{
	"@context": "https://schema.org",
	"id": "abc",
	"type": "MovieTheater",
	"name": "ABC"
}

If so, what's the best practice for doing so? Would it be best to use an aliased @included ? Or would the initial response be a "Collection of Collections"? If so, should hasPart be an id map? or would it be better to drop that and use custom properties of some kind?

[gkellogg]

This is the intended purpose of @included, to contain objects associated with, but not necessarily directly referenced by other objects in the same document. However, if "location" is of type @id, the included document could be used as the value of "location" rather than just "abc". It need only be used once, but can be used in both locations, which may be the right thing for a given API. Framing allows you to make these distinctions using @embed, so it's reasonable to author a document that way as well.

[davidbarratt]

@gkellogg Thank you so much for your quick response.

I was assuming that location would be of type @id. I wasn't sure if it was better for API consumers if an identical object would be embeded multiple times, exist only on one of the objects, or be in a completely separate "list".

It sounds like, in general, it is better to simply embed it multiple times?

[gkellogg]

@gkellogg Thank you so much for your quick response.

I was assuming that location would be of type @id. I wasn't sure if it was better for API consumers if an identical object would be embeded multiple times, exist only on one of the objects, or be in a completely separate "list".

It sounds like, in general, it is better to simply embed it multiple times?

I'm not sure you can make a generalized case either way. Each implementation will need to chose how best to satisfy their clients. Embedding multiple times can be useful, when it doesn't lead to too much bloat.

JSON-LD has a number of different mechanisms to tailor the results for different audiences. As you may recall, the design choice for JSON-LD is to give JSON meaning by unambiguously interpreting the content, which is because different endpoints will make different design choices.