w3c / w3c/json-ld-api

Graph-aliased keywords don't work as containers in JSON-LD 1.1

Open
#536 2 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

ms:future-work spec:enhancement
Dominant language
HTML
Stars
106
Forks
40
PR merge metrics
No merged PRs in 30d

Description

It appears that @graph-aliased keywords don't work as containers in JSON-LD 1.1. Given:

{
  "@context": {
    "@base": "https://example.org/",
    "@vocab": "https://example.org/ns/",
    "entities": {
      "@id": "@graph",
      "@container": "@index"
    }
  },
  "entities": {
    "Q102071": {
      "@type": "item",
      "@id": "Q102071"
    }
  }
}

I'd expect the following:

[
  {
    "@id": "https://example.org/Q102071",
    "@type": [
      "https://example.org/ns/item"
    ],
    "@index": "Q102071"
  }
]

I haven't positively checked that this is a regression from 1.0, but I am quite sure that the intent has always been to support this. Alas, there seems to be no such form in the test suite (in fact, no @graph-aliases at all, to my surprise), otherwise it'd been caught.

This actually works in the JSON-LD 1.1 playground, and in RDFLib.

Crucially though, it does not work according to the JSON-LD 1.1 Expansion Algorithm, where step 13.4 and 13.4.5 creates an expanded value and continues (in 13.4.17), thus bypassing the container processing step at 13.5.

Thus it doesn't work in the faithfully implemented Ruby RDF distiller, nor in TRLD (equally faithfully implemented I hope).

The fix is simple: just exclude @graph in step 13.4 (and thus step 13.4.5 can just be removed). I tried that in the TRLD implementation, and if this is acknowledged, I'd like to fix this in the spec (at least getting it into JSON-LD 1.2).

This appears to work in the compaction algorithm, at least if the expanded graph array is wrapped in a graph object, i.e. given:

{
  "@graph": [
    {
      "@id": "https://example.org/Q102071",
      "@type": [
        "https://example.org/ns/item"
      ],
      "@index": "Q102071"
    }
  ]
}

Combined with the context from the initial example, and fed into compaction unaltered, that will be compacted into the form of that example.

We may want to clarify that the compaction algorithm must ensure that it is thusly wrapped if it is given an array, or at least spell it out that for compaction using graph aliases to work, it needs that form (with an outer graph object) as input.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the JSON-LD 1.1 Expansion Algorithm at steps 13.4, 13.4.5, and 13.5, using the provided graph-aliased @index example as the reproduction. Check the corresponding compaction behavior and add coverage for expansion and compaction; done when the example produces the expected node with @index and graph aliases remain supported.

Written by the indexing model from the issue text.

Assessment

Tech stack
json
Domain
documentation
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.