w3c / w3c/json-ld-api

Various `@json` processing issues.

Open
#560 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

defer-future-version ErratumRaised substantive:class 4 test:missing-coverage
Dominant language
HTML
Stars
106
Forks
40
PR merge metrics
No merged PRs in 30d

Description

The 1.1 spec and test cases are missing coverage of how to handle various @json processing issues and possible data.

This work started when looking into a a jsonld.js issue about compacting a JSON literal array:
https://github.com/digitalbazaar/jsonld.js/issues/509

Part of that issue is a jsonld.js issue, but test coverage doesn't exist for all this (yet), and it's unclear how to handle various situations. So I fell down the hole of exploring this.

Handling JSON literal arrays has some rough spots. The compact/js07 test would seem to indicate even if @set is used, a jSON literal is not put in an array, which is not what would expect based on:
https://www.w3.org/TR/json-ld11/#representing-singular-values-as-arrays.

But if @set creates an array of JSON literal values, then the parsing code would need to know this is a @set, otherwise it would be interpreted directly as a JSON literal array.

A related situation is if you try to compact multiple values to a @json term. If it uses an array, then a parser would see that literal array.

An oddity of jsonld.js is that if you compact JSON and non-JSON values to a @json term, it will use the compacted term for the JSON, and the expanded term for the non-JSON. I'm not sure if that is correct, or just a quirk of implementation and @json matching of some sort.

I wrote a variety of tests to cover many situations. As a first pass, I made the tests do what seemed like would "make sense", but they may not match specs. This in no way covers all the ways these features can be used or misused. This @json feature seems to add more complexity than expected.

  • Change compact/js07 compaction output for @json and @set of a JSON literal array. Add an array around whatever the literal was, in this case a literal array.
  • Propose new multiple JSON literals error code when trying to add multiple JSON literals as values for a property not declared a @set.
  • Use invalid set or array object when expanding a @json term declared a @set or @list and an array is not used.
  • Various combinations of these things.

The above is by no means exhaustive. Other constructs probably also need more explicit @json handling and tests. Help needed.

The above would at least allow JSON literals to be used as single values, as multiple values in explicit sets and lists, and for expansion and compaction, and I think all would work for round trips.

I think use of @json that causes these issues has been minimal so far. It would be good to add test coverage for expected behavior and update specs as needed to handle various use cases.

First pass at test cases: https://github.com/w3c/json-ld-api/pull/559

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 by reviewing the 1.1 specification, the compact/js07 test, the other test cases described in the issue, and the linked pull request 559. Compare the proposed cases with the JSON-LD 1.1 requirements and existing behavior; done means the expected @json handling is agreed, specified, and covered by tests.

Written by the indexing model from the issue text.

Assessment

Tech stack
json
Domain
documentation, testing
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
15/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.