Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

JSON-LD emerging best practice is to alias @type, @id (and other keywords) #854

Open
danbri opened this Issue Oct 28, 2015 · 18 comments

Comments

Projects
None yet
7 participants
@danbri
Copy link
Contributor

danbri commented Oct 28, 2015

Let's add these aliases to our context file as this is harmless and somewhat useful. Whether as a project we want to encourage people to write (and consume) "type" instead of "@type" is a larger discussion.

see http://www.w3.org/TR/json-ld/#syntax-tokens-and-keywords

danbri added a commit that referenced this issue Oct 28, 2015

First step towards #854 - supporting @-free keywords for at least @type
…, @id

TODO: add other keywords; investigate if there is consensus amongst consumers
to encourage this usage.
@danbri

This comment has been minimized.

Copy link
Contributor Author

danbri commented Oct 28, 2015

@lanthaler

This comment has been minimized.

Copy link
Collaborator

lanthaler commented Oct 28, 2015

Sorry, I missed all the discussions about this. What is motivating this? How will we deal with collisions? For instance value and language in case of schema.org?

@dlongley

This comment has been minimized.

Copy link

dlongley commented Oct 28, 2015

@lanthaler, I think the proposal is for aliasing @id and @type not @value and @language. The former two are likely to appear in compacted documents and not using the @ makes for more developer-friendly docs (you can, for example, use dot notation to access their values). The latter two are less likely to appear in compacted documents as they are often hidden away via context rules.

@danbri

This comment has been minimized.

Copy link
Contributor Author

danbri commented Oct 28, 2015

Yes, I think @id and @type are vastly the most common constructs appearing in typical data. I do not mind seeing @blahblah for other things, but it would be nice for people to be able to avoid the @ in very simple plain descriptions.

@lanthaler

This comment has been minimized.

Copy link
Collaborator

lanthaler commented Oct 28, 2015

I do understand that this proposal is about @id and @type explicitly but that leaves the question open what happens with the other keywords. Treating certain keywords differently causes inconsitencies and confusion IMO. Also, basically all documentation out there, every tutorial, etc. uses the @-prefixed keywords. It makes it very simple to understand where things come from.
@danbri, have you seen people having issues with @id and @type?

@danbri

This comment has been minimized.

Copy link
Contributor Author

danbri commented Oct 29, 2015

@lanthaler I have seen people puzzled by "what's the @ sign for?". /cc @jvandriel @Aaranged for mainstream publisher perspective. I don't think it is a big issue either way. It makes the simpler case a little simpler, and leaves the complex case untouched.

The other motivation here (see linked issues in other repos above) was from different W3C-centric communities who are also working with JSON-LD schemas in other settings (annotation, social Web, ...) and want to make sure the @ does not scare away *-LD-agnostic developers. Users of those specs should not have to memorize a list of which common schema projects have aliased away the @ for these common cases.

Although in theory the use of the '@' prefix notation protects vocabulary terms from clashing with JSON-LD keywords, in practice it is still probably best for (new) vocabularies that anticipate being used via JSON-LD to avoid using the exact same words if they can.

The current change addresses the case of:

  • publisher forgets/omits the '@' sign on id or type
  • consumer is using general context-file based consumption of schema.org

When those two are the case, i.e. consumer is actively reading the context file we publish at schema.org, then we can make such small data 'bugs' matter less. This seems reasonable.

I think we should also do one more workflow thing here, which is to add a sanity-preservation QA unit test in our tests/ collection that ensures we do not ever create a property or type or enumeration called 'type' or 'id'. And likewise for any remaining JSON-LD special keywords beyond those (@Keywords, @language, others?) where we already have a clash. We can't make the existing clash go away but we can avoid compounding that issue further.

@danbri

This comment has been minimized.

Copy link
Contributor Author

danbri commented Oct 29, 2015

+cc @msporny

@dlongley

This comment has been minimized.

Copy link

dlongley commented Oct 29, 2015

👍 @danbri

@azaroth42

This comment has been minimized.

Copy link

azaroth42 commented Oct 29, 2015

👍 from the Annotation WG, we've made the change already:
http://w3c.github.io/web-annotation/model/wd/

@akuckartz

This comment has been minimized.

Copy link

akuckartz commented Oct 29, 2015

This is a duplicate of #286. The "distant, hazy future" seems to have arrived :-)

@jvandriel

This comment has been minimized.

Copy link

jvandriel commented Oct 29, 2015

@lanthaler I have seen people puzzled by "what's the @ sign for?"

I haven't run into this remark/question yet. Although I guess the cause for this is that your run of the mill SEO/marketer isn't using JSON-LD all that much yet since Google doesn't generate rich snippets for all types they support in microdata; And I can very well imagine this will change once Google fully supports JSON-LD for rich snippets.

Though even without taking SEOs/marketers into account I think adding these aliases is a good idea. Forgetting to type the '@' symbol is a typo that easily happens (I admit it happened to me already), so building in a failsafe does seem like a worthwhile effort to me.

@lanthaler

This comment has been minimized.

Copy link
Collaborator

lanthaler commented Oct 29, 2015

I completely agree with adding it to the context as a safety net. I wouldn't like to see the examples etc. being changed however; or any other promotion of the @-less keywords for that matter. I think it is important that people can go from the example, do a simple Google query for JSON-LD (or the application/ld+json they see in the examples) and get to the description of the keywords. Keyword aliasing is an advanced feature and should remain such.

Just as @jvandriel I haven't 'seen people puzzled by "what's the @ sign for?".' yet... and I have talked to quite a few people about JSON-LD and presented it at numerous conferences. It's quite easy to understand (and to describe) that JSON-LD keywords start with an @. Once you remove it becomes difficult to understand what is a keyword and what a property from a vocabulary without looking at the context.

@azaroth42

This comment has been minimized.

Copy link

azaroth42 commented Oct 29, 2015

We have seen:

  • Confusion about the @Sign, especially with rdf:value / @value, dc:language / @language. This doesn't solve that confusion, as only id and type are aliased, but it helps as id and type are more common.
  • And more frequently, unnecessary frustration for not being able to do dot notation: foo.@type is a syntax error in most languages

@type is (at least in one of its uses) a property from a vocabulary. It's (as you know) "type" from the rdf ontology. So it's actually not any more difficult to understand than it already was. I don't buy that argument at all, sorry. Also, the aliasing is intended to make the JSON seem more familiar to developers and users for the aspects that are most commonly used. They don't care at all about the distinction between a JSON-LD keyword and a term from a vocabulary, it should appear as just JSON in a particular structure. For the people that do care about the RDF layer, it's easy to see the mapping in the context.

@danbri

This comment has been minimized.

Copy link
Contributor Author

danbri commented Oct 30, 2015

Ok I think we're pretty much converged here, at least for now.

But I can't resist trying to get the last word with @lanthaler ;)

Regarding,

  • "It's quite easy to understand (and to describe) that JSON-LD keywords start with an @"

That makes perfect sense when talking to people who have any interest in understanding what JSON-LD is. At schema.org we have to consider publishers who often barely distinguish JSON and Javascript, and have very little immediate interest in even hearing about JSON-LD. Once you find someone with that interest, it is indeed relatively easy to get across the idea of keywords.

@lanthaler

This comment has been minimized.

Copy link
Collaborator

lanthaler commented Oct 30, 2015

For people just interested in schema.org but not in JSON-LD you simply tell them that anything starting with @ can't be found on schema.org as it wasn't defined by it. In other words, the schema.org/{xxx} lookup "trick" doesn't work for those things.

As already said, I'm fine with the concrete changes that have been made but think pushing this too far does more harm than good.

@id has a very specific purpose (and isn't used much with typical schema.org use cases anyway) and a special processing model different from anything else. There are heaps of valid uses of id out there already as a quick query shows: http://lov.okfn.org/dataset/lov/terms?q=id

A last quick comment regarding @type: that has indeed been a problematic one from the start. We used to have two keywords (@datatype) but that confused people even more. The root cause of this lies in the fact that RDF needed to special case this as it doesn't support literals in subject position. To work around that, a literal now consists of two (and in a single case, three) components.

@danbri

This comment has been minimized.

Copy link
Contributor Author

danbri commented Oct 31, 2015

I've made a note too #860 to make sure that http://schema.org/id and /type 404 handler provides sensible hints / links / documentation.

We do this already e.g. for the pseudo-property notation used with Action e.g. http://schema.org/name-input which isn't really a property, but relates to /name.

@Lomilar

This comment has been minimized.

Copy link

Lomilar commented May 18, 2017

Please note that this practice has started to cause some irregularity in how JSON-LD processors work. For instance, the JSON-LD compact operation in the jsonld-java library currently unwinds @id and @type of schema.org objects to id and type. The jsonld npm library compact operation doesn't unwind @id and @type in the first level of a JSON-LD object, but typed subobjects get @type unwound to type.

This also creates a bit of a trap. When defining a context, if "id":"@id","type":"@type" is followed as a best practice, and "@vocab":"..." is not used, then id and type have no namespace. This has happened here.

Edit: Keyword aliases are special, and not subject to namespace requirements.
Edit 2: I'm an idiot.

@azaroth42

This comment has been minimized.

Copy link

azaroth42 commented May 18, 2017

That sounds like a bug in the NPM library.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.