search

w3c / json-ld-syntax

JSON-LD 1.1 Specification
https://w3c.github.io/json-ld-syntax/
Other
112 stars 22 forks source link

Inconsistencies in how @vocab is specified #184

Closed pchampin closed 5 years ago

pchampin commented 5 years ago

Section 9.15 (normative) specifies that @vocab's value

MUST be a absolute IRI, a relative IRI, a compact IRI, a blank node identifier, an empty string (""), a term, or null.

Section 1.4 (non-normative) defines "vocabulary mapping" as

using the @vocab key whose value MUST be an IRI or null.

Finally, the "Changes" section of the API document says

The empty string ("") has been added as a possible value for @vocab in a context.

I consider those changes to be editorial, so they may not need a resolution, but I would rather have a second opinion before submitting the changes.

pchampin commented 5 years ago

Actually, Section 1.4 is also normative, which makes this problem even more serious.

gkellogg commented 5 years ago

Section 9.15 (normative) specifies that @vocab's value

MUST be a absolute IRI, a relative IRI, a compact IRI, a blank node identifier, an empty string (""), a term, or null.

  • The empty string is a special case of a relative IRI → suggest to remove.

Yes, this was missed before.

  • Furthermore, I don't understand what it would mean to have compact IRIs and terms as @vocab. Anyway, they are undistinguishable from IRIs (absolute and relative, respectively) → suggest to remove (but I may be missing something).

We typically allow compact IRIs wherever absolute IRIs can be used, so not allowing it here would be the exception, but it's probably not an important use case.

Section 1.4 (non-normative) defines "vocabulary mapping" as

using the @vocab key whose value MUST be an IRI or null.

  • I don't know if "IRI" is supposed to encompass terms and compact IRIs -- but assuming that I was right above, this does not matter anymore.

Need to make consistent with other definitions.

  • However; this definition does not mention blank node identifiers, which are normatively allowed by section 9.15. It may be a mistake, or a deliberate decision since this is non-normative text and blank node IDs as vocab are discouraged in the API document. However, I think it is a bad idea to have two parts of the document contradicting each other → suggest to add "or blank node identifier".

We were trying to obsolete the use of blank node identifiers for @vocab, so didn't want to call it out, but maybe something is necessary to describe what's legal, with a WARNING to discourage it.

Finally, the "Changes" section of the API document says

The empty string ("") has been added as a possible value for @vocab in a context.

  • In the meantime, we have extended this to allowing any relative IRI → suggest to change

The first note was for an earlier change, but it should be eliminated in favor of the relative IRI.

I consider those changes to be editorial, so they may not need a resolution, but I would rather have a second opinion before submitting the changes.

Agreed they're editorial.

gkellogg commented 5 years ago

Based on my review comment in https://github.com/w3c/json-ld-api/pull/129#pullrequestreview-272081242, we should probably either not discuss using compact IRIs or terms for @vocab, or provide a caveat that any terms used as part of @vocab must be in scope when the context is introduced, due to circular definition issues.