Question about good practice for @id

[cristianvasquez]

Hello,

I'm looking at this document: https://json-ld.org/spec/latest/json-ld-api-best-practices/

Where Best Practice 8, "Identify objects with a unique identifier," says:

'Entities described in JSON objects often describe web resources having a URL; entity descriptions SHOULD use an identifier uniquely identifying that entity. In this case, using the resource location as the identity of the object is consistent with this practice.'

This mechanism allows a client to follow, without effort, links to other entities in the Web.

But sometimes @id have a context on it like in:

{
  "@context": {
    ...
    "image": { "@id": "schema:image", "@type": "@id"},
    ...
  }
}

In this case, the client needs to be smart enough to build the URL to follow links.

Question: could be considered a good practice to provide URLs in @id when possible?

[pchampin]

There are two things at play here.

First thing: whenever the value of @id has the form prefix:suffix, it must be expanded to a URL, by substituting prefix: with the URL associated to prefix in the @context. So

{
    "@context:" {
        "schema": "http://schema.org/",
        "name": { "@id": "schema:name" }
    }
}

is roughly equivalent to

{
    "@context:" {
        "name": { "@id": "http://schema.org/name" }
    }
}

NB: this kind of expansion is also happening in other places in JSON-LD; I'm focusing on @id because that was your question.

Second thing: @id inside a context has a slightly different meaning than in the rest of the data.

{
    "@context:" {
        "creator": { "@id": "http://schema.org/creator" }
    },
    "@id": "http://champin.net/",
    "creator": { "@id": "Pierre-Antoine Champin" }
}

In the example above,

• the first @id (3rd line) is part of a term definition; it basically says "creator should be interpreted as http://schema.org/creator;
• the other occurences of @id (5th and 6th line) say "this JSON object represents an entity whose identifier is ...".

So the outer JSON object represents an entity identified by http://champin.net/ (i.e. my homepage); the inner JSON object at line 6 represents an entity identified by http://champin.net/#pa (i.e. myself); the creator attribute states, per the context, that these entities are in a relationship identified by http://schema.org/creator.

[cristianvasquez]

Hello,

Thank you for the quick answer.

My question was regarding the first meaning of @id, outside the context. (btw, why having two meanings?)

Perhaps I can rephrase this question into another:

When is convenient to expand prefix:suffix to URLs when publishing json-ld?

[gkellogg]

@cristianvasquez said:

In this case, the client needs to be smart enough to build the URL to follow links.

No, there is no implicit following of links. As @pchampin said, schema must already be a defined term. This form is called a Compact IRI, where the prefix is the IRI of some vocabulary, and the suffix is a term defined within that vocabulary. It's only valid when schema is already defined (otherwise, it's treated as an IRI scheme).

My question was regarding the first meaning of @id, outside the context. (btw, why having two meanings?)

Not really, in both cases they mean the identity of the thing, it's just that in the context, it's the identity of the term, and in the body, it's the identity of the node.

When is convenient to expand prefix:suffix to URLs when publishing json-ld?

Note that it's somewhat controversial that JSON-LD even has the compact IRI syntax, as many people don't care for the use of namespaces, which is effectively what they are.

It's useful when defining terms to use the compact IRI form to reduce space (and potentially typing) when several terms come from the same vocabulary. In the case of schema.org, you might avoid it by setting the default vocabulary using @vocab in the context, then all terms will be assumed to be part of that vocabulary. In other cases, multiple vocabularies are used, for example the "foaf" and "dc" prefixes used within the spec.

Compact IRIs may show up in the body after doing compaction or framing when properties come from defined vocabularies without terms being explicitly defined. This is probably more common when turning arbitrary RDF into JSON-LD, rather than for pure-JSON use.

[cristianvasquez]

@cristianvasquez said:

In this case, the client needs to be smart enough to build the URL to follow links.

No, there is no implicit following of links. As @pchampin said, schema must already be a defined term. This form is called a Compact IRI, where the prefix is the IRI of some vocabulary, and the suffix is a term defined within that vocabulary. It's only valid when schema is already defined (otherwise, it's treated as an IRI scheme).

My question was regarding the first meaning of @id, outside the context. (btw, why having two meanings?)

Not really, in both cases they mean the identity of the thing, it's just that in the context, it's the identity of the term, and in the body, it's the identity of the node.

When is convenient to expand prefix:suffix to URLs when publishing json-ld?

Note that it's somewhat controversial that JSON-LD even has the compact IRI syntax, as many people don't care for the use of namespaces, which is effectively what they are.

It's useful when defining terms to use the compact IRI form to reduce space (and potentially typing) when several terms come from the same vocabulary. In the case of schema.org, you might avoid it by setting the default vocabulary using @vocab in the context, then all terms will be assumed to be part of that vocabulary. In other cases, multiple vocabularies are used, for example the "foaf" and "dc" prefixes used within the spec.

I just realized that my original question should have been: when to use each application/ld+json profile? ( expanded, compacted, and flattened)

I guess there is no unique answer... compacted is good for humans and to reduce space, but requires that clients understand JSON-LD and to expand URLs. Perhaps one can choose the default profile depending on the case, agent, etc.

Compact IRIs may show up in the body after doing compaction or framing when properties come from defined vocabularies without terms being explicitly defined. This is probably more common when turning arbitrary RDF into JSON-LD, rather than for pure-JSON use.

Thanks!

[pchampin]

I just realized that my original question should have been: when to use each application/ld+json profile? ( expanded, compacted, and flattened)

In general, there are 2 ways to consume JSON-LD data.

The first way is when clients are aware that the data is JSON-LD (rather than plain JSON). They are therefore supposed to know about the JSON-LD API, and can "juggle" between the different representations (compact, expanded, flat) depending on their needs. In particular, they would rely on expansion to resolve compact IRIs (foo:bar) into absolute IRIs.

The second way is when clients consider JSON-LD as plain JSON. These clients expect a compact form, that complies with a given "format" (possibly described with a JSON-schema or a similar specification). These kinds of clients are supposed to have the format's semantics built-in.

So to answer your question about best practices: if you only target the first kind of clients, then compact IRIs should not be a problem. If you target both kinds of clients, then your compact form will have to comply with the JSON-based format expected by the 2nd kind. The vast majority of such formats do not use compact IRIs, so indeed, that will generally mean using absolute IRIs. But this is dictated by the format to which your JSON-LD context aims to align, not by JSON-LD itself.

[iherman]

I believe that the duality described in #7 (comment) by @pchampin is expressed as an explicit issue: namely #19.

@pchampin @cristianvasquez is it o.k. to close this issue and let #19 take its course?

[pchampin]

Ok for me, but this is @cristianvasquez's issue :)

[cristianvasquez]

Thanks ! :)