Repository navigation
Type Coercion / Node Conversion: @coerce keyword or similar #335
Description
I have an idea for a future version of JSON-LD.
As a web developer, I would like to receive a JSON document from i.e. a simple API, add a @context to it, and perform JSON-LD operations. This light approach has been a big selling point to me for using JSON-LD.
A common response from such an API may include an "id" property as a number (as it is indexed in the source database as an integer), so after applying the @context the document may look like this:
{
"@context": {
"@base": "http://starwars.com/",
"@vocab": "http://starwars.com/",
"id": "@id",
"type": "@type"
},
"id": 123,
"type": "Human",
"firstName": "Luke",
"lastName": "Skywalker"
}Currently, the expansion step will generate an error:
Invalid JSON-LD syntax; "@id" value must a string.
My intention in declaring the @base was to form the IRI "http://starwars.com/123". I don't think this kind of type coercion is currently possible with JSON-LD.
The alternative would be a blank node with a custom ID property, which is less useful in certain situations.
I propose a solution that coerces the XSD type, so that when flattened, it becomes:
[
{
"@id": "http://starwars.com/123",
"@type": [
"http://starwars.com/Human"
],
"http://starwars.com/firstName": [
{
"@value": "Luke"
}
],
"http://starwars.com/lastName": [
{
"@value": "Skywalker"
}
]
}
]
As a starting point, I suggest adding a keyword called @coerce.
I originally opened this as an issue in Framing and got some helpful feedback from @gkellogg:
This would probably be in compaction/expansion rather than framing. It is somewhat similar to the useNativeTypes option for fromRdf.
It’s a common idiom in JSON, so it’s worthy of future consideration.
Activity
ioggstream commentedon Jan 31, 2022
Related to #386
ioggstream commentedon Jan 31, 2022
@michaelcpuckett
if you reflect in this use case too, I can close #386 and continue under this issue.re-reading this issue I understand it's only related to
integervalues, sorry for the confusion.VladimirAlexiev commentedon Feb 1, 2022
jsonld.SyntaxError: Invalid JSON-LD syntax; "@id" value must a string.is extremely unpleasant.At least that's what the playground produces: https://tinyurl.com/ya7g4n9y.
@msporny @gkellogg
But is that mandated by the spec? Why can't I make a URL out of an integer, or even a boolean?
msporny commentedon Feb 1, 2022
Every feature that we add to JSON-LD makes the implementation burden harder for implementers, and understanding the standard harder for developers, which results in worse interoperability and authoring outcomes.
Yes, it would be nice if JSON-LD processors did this, but at the same time, this is the first time (that I know of) that this has come up during the 10+ years that JSON-LD has existed.
When it comes to things like this, we've suggested that developers first just write a quick function to do some pre-processing on their JSON. For example, a function that runs over a JSON object and turns all "id" values to
strings would be a fairly trivial piece of code to write. If we try to put it in the next standard... it'll take 2-4 years for that feature to happen. Given that this is the first time that this feature has been requested, given how long it takes features to be standardized, and given that I expect this need to not be shared among many... write a few lines of code and solve the problem in a way that works for you today.If we get lots of people clamoring for this sort of type coercion, we can come back and revisit the feature request.
Again, the feature is easy to implement... it's getting the standard updated, implementations updated, test suites updated... that's what'll take time.
An alternative way to address this is to convince the implementers to provide "pre-processing" functions that they can register w/ the JSON-LD processor. So the processor would always run these pre-processing functions before doing the JSON-LD standard operations. Food for thought.
rob-metalinkage commentedon Sep 4, 2025
It is very surprising this has not been raised often.
For added incentive, there is an lot of noise currently around Model Context Protocol - https://modelcontextprotocol.io which uses a base schema called JSON-RPC
leaving aside the rationale for this, it is nevertheless appearing in many tool chains... and it allows integer IDs
Its also super common in GIS backed GeoJSON outputs - since most GIS systems use numerical object ids by default.
I havent unpacked implementations to determine how many use integers vs strings..
I think by the time you include a significant portion of geography and AI applications this issue starts to become more urgent - its a huge barrier to JSON-LD adoption, since otherwise we could simply "upgrade" all these with a JSON-LD context and make them processable in graphs without custom code pipelines.