w3c / w3c/json-ld-api

What should happen when `@container` is the empty array

Open
#718 0 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
HTML
Stars
106
Forks
40
PR merge metrics
No merged PRs in 30d

Description

I don't think anyone would legitimately set @container to the empty array, I can't imagine why you would. I can see it getting emitted by JSON serialisation libraries for null or absent.

Reading the spec I'm reasonably convinced that this should raise an error. But the test suite doesn't have cases for it, and it seems to work on the JSON-LD Playground/jsonld.js.

If folks agree with my interpretation I can send in a few test cases.


Empty @container on a regular term

Given an input of:

{
  "@context": {
    "term": {"@id": "http://example.com/term", "@container": []}
  },
  "term": "http://example.com/test#example"
}

In step 19 of Create Term Definition:

If value contains the @container:
19.1) Initialize container to the value associated with the @container, which MUST be either @graph, @id, @index, @language, @list, @set, @type, or an array containing exactly any one of those keywords, an array containing @graph and either @id or @index optionally including @set, or an array containing a combination of @set and any of @index, @graph, @id, @type, @language in any order. Otherwise, an invalid container mapping has been detected and processing is aborted.

(It may also be nice to reword 19.1 because that sentence is a lot. Splitting it out into its own bullets may make it easier to follow. One other thing I'm not sure about is whether the order for what is in the array is relevant. It's explicitly called out in case it contains @set. For the other cases that would seem to suggest the order in which we spell them out is relevant?)

Since the empty array doesn't satisfy the requirements imposed on array, I would expect this to fail. We don't have a test for this, and the JSON-LD playground expands it to:

[
  {
    "http://example.com/term": [
      {
        "@value": "http://example.com/test#example"
      }
    ]
  }
]

Empty @container on an @reverse term

I think we have a similar case with @reverse and the empty @container.

Given an input of:

{
	"@context":{
		"term":{"@reverse":"http://example.com/term","@container":[]}
 	},
	"term":{}
}

In step 13 of Create Term Definition:

If value contains the entry @reverse:
13.5) If value contains an @container entry, set the container mapping of definition to an array containing its value; if its value is neither @set, nor @index, nor null, an invalid reverse property error has been detected (reverse properties only support set- and index-containers) and processing is aborted.

Here I also think we should do the value check first, before the arrayification. Turning it into the array is a bit pointless if it doesn't have a valid value.

However, we lack a test for this too. In the case of the JSON-LD Playground, it expands to:

[
  {
    "@reverse": {
      "http://example.com/term": [
        {}
      ]
    }
  }
]

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 Create Term Definition steps cited in the issue and inspect the existing test suite for invalid container and reverse-property cases. Add cases for an empty @container on a regular term and an @reverse term, verifying that processing raises the appropriate error. Done means the tests capture the expected failures and clarify whether the specification wording needs revision.

Written by the indexing model from the issue text.

Assessment

Tech stack
json
Domain
documentation, testing
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.