w3c / w3c/json-ld-api

Algorithm Terms and IRI expansion algorithm contradict each other

Open
#642 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

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

Description

In section 1.4.1 Algorithm Terms (emphasis mine):

IRI expanding
Used as a macro within various algorithms as to reduce the language used to describe the process of expanding a string value representing an IRI or keyword using an active context either specified directly, or coming from the scope of the algorithm step using this term. Optional defined and local context arguments are used, if explicitly provided. Unless specified, the document relative flag defaults to false, and the vocab flag defaults to true.

  • default relative: false
  • default vocab: true

In section 5.2.2 IRI Expansion Algorithm (emphasis mine):

The algorithm takes two required and four optional input
variables. The required inputs are an active context and a
value to be expanded. The optional inputs are two flags,
document relative and vocab, that specifying whether value
can be interpreted as a relative IRI reference against the
document's base IRI or the active context's vocabulary
mapping, respectively, and a local context and a map
defined to be used when this algorithm is used during
Context Processing. If not passed, the two flags are set to
false
and local context and defined are initialized to null.

  • default relative: false
  • default vocab: false

Step 13.4.4 of expansion, section 5.1.2, does not specify the value for vocab, so I went with false as per the default specified by the IRI expansion algorithm. This makes things not work. Seeing as step 13.4.3 explicitly specifies false for vocab it does seem like the default should be true and the IRI expansion algorithm introduction contains a mistake.

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

Compare the defaults stated in section 1.4.1, the IRI Expansion Algorithm introduction in section 5.2.2, and steps 13.4.3–13.4.4 of section 5.1.2. Confirm which vocab default makes the algorithm consistent, then update the contradictory specification text so the stated defaults and expansion behavior agree.

Written by the indexing model from the issue text.

Assessment

Tech stack
json
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.