Given the best practice to alias @id and @type, it seems valuable to also have an alias without the @ symbol for @none.

This would allow javascript like:
alert(object.label.none)

In the same way as:
alert(object.label.en)

Which is more lovely than:
alert(object.label['@none'])

this should end up in https://github.com/orgs/w3c/projects/84

@w3c/json-ld-wg-admin was there a reason we didn't bring over the CG's Best Practices content?

If not, then I'd like to use that as a foundation to build up from.

@ajs6f thoughts?

As evidenced by reports, there is some confusion about how to use multilingual data values alongside language maps. @pchampin noted that using an alias is a good way to work through this, and @BigBlueHat noted (link to minutes forthcoming) that this is the approach taken by Web Annotations. We should offer some examples of this practice, probably in the context of the (long-promised) Primer.

We should use either one of our own GH id-s or somebody anonymous....

Coming from today's WoT Thing Description meeting:

We wondering if there is a standardized place where we can find the Frame and/or validation document (eg, SHACL, JSON Schema,... ) for a specific context. Can be this placed within the context file or what is the recommendation?

Hi,

the examples use "@context": "http://schema.org" while schema.org states that the context is found elsewhere:
https://schema.org/docs/developers.html

It should be "@context": "https://schema.org/docs/jsonldcontext.json",

Consider best practices around the documentation of contexts and frames.

Options include:

• Content Negotiation on the context document URI to get either the JSON-LD or human readable documentations (#43)
• Embedding contexts in HTML, and having them extracted via processing [Would have a normative effect on -syntax?]
• Data in the body of the context document
• An ignored keyword in the context referencing external resource (#42)
• An ignored keyword in the context that embeds data (#32, #40)

To be considered during CR/PR phase as best practices. WG consensus is not to pursue this as a normative requirement.

I believe we should add explicit examples on how to add cache control, possibly as .htaccess or apache config code.

I'd like to rename the BP to "JSON-LD Best Practices" (removing the 1.1), and break the sections up into:

• Authoring
  • contexts
  • data documents
• Publishing
• Consuming

Including lists of lists.

(From call on 2020-02-14)

Following #4, we can add guidelines for achieving streaming JSON-LD, and any restrictions it may bring.
Here is a summary of the issues discussed in #4.

Guidelines:

1. The structure of a JSON-LD document to enable efficient streaming parsing to RDF.
   1. If there is an @context in a node, it should be the first key.
   2. If there is an @type in a node, and its value indicates a type-scoped context, it should come right after an @context (if there is one), or be the first key.
   3. If there is an @id in a node, it should be the first key if there is no @context or @type, or the second (or third) key if there is an @context or @type.
2. The order in which RDF triples/quads should appear to enable efficient streaming serialization to JSON-LD.
   1. Quads with equal graphs should be grouped (Achieves grouping of @graph blocks).
   2. Quads with graph corresponding to the subject of triples/quads should be grouped (Achieves grouping of @graph and @id blocks).
   3. Triples with equal subjects should be grouped (Achieves grouping of @id blocks).
   4. Triples with equal predicates should be grouped (Achieves grouping of predicate arrays)

(triple stores may already do these kinds of grouping automatically)

Restrictions:

1. Parsing
   • The spec allows @context to appear any in the document. As such, a strict parser may require buffering large portions of the stream. However, since most real-world JSON-LD documents place @context as first element, streaming parsers may reject any JSON-LD documents that have out-of-order @context's.
2. Serialization
   • RDF lists are not converted to @list arrays, as you can only be certain that @list can be used once all triples have been read, which requires keeping the whole stream in-memory.
   • No deduplication of triples, as this would also require keeping the whole stream in-memory.

While reading w3c/pub-manifest#65 I tested the following JSON-LD in the playground:

{
  "@context": {
    "name": {
      "@id": "http://example.com/name",
      "@type": "xsd:string"
    }
  },
  "name": true
}

This resulted in this unexpected (by me) expanded form:

[
  {
    "http://example.com/name": [
      {
        "@type": "xsd:string",
        "@value": true
      }
    ]
  }
]

Obviously...that's incorrect and I'd expected a warning, error, or (perhaps) type coercion.

Reshaping it a bit, I added a @language tag, and that did throw a more expected error:

{
  "@context": {
    "name": {
      "@id": "http://example.com/name",
      "@type": "xsd:string"
    }
  },
  "name": {
    "@language": "en",
    "@value": true
  }
}

Ask here is to see if we could make this more obvious. 😄

See:
w3c/json-ld-wg#98
w3c/json-ld-wg#100

Given the complexity of resolution in the wild, it's best to use absolute URIs if at all possible, and that is what we should recommend.

As discussed on 2018-07-06 call, one aspect of the work is the extent to which JSON-LD instances can be round tripped through RDF, and vice versa.

In particular, questions arose as to:

• Should any valid RDF graph be able to be serialized 100% faithfully in JSON-LD, such that it can be parsed back to the exact same graph?
• Conversely, should any JSON-LD instance be able to be parsed to an RDF graph, and back to the same JSON-LD?

Currently the answer to both questions is no:

• RDF has constructs that cannot be serialized to JSON-LD: An rdf:List of rdf:Lists is not able to be serialized
• JSON-LD allows constructs that are not valid in RDF: Properties can be blank nodes

Work to be done:

• Discuss the degree to which support for round tripping, in each direction, is important to us.
• Determine the extent to which round tripping is not possible for both directions, with references to the specs.
• Provide test cases for each non-round-tripping scenario
• Document in the specs where round tripping is not possible

Current taskforce: @azaroth42 @workergnome @gkellogg @mixterj (add yourself if you're interested!)

Following the discussion in w3c/json-ld-syntax#153, it would be good to add an example to the BP document of non-trivial @protected usage that does not throw an error.

The following (error-throwing) example is present in the syntax spec:

{
  "@context": [
    {
      "@version": 1.1,
      "Person": "http://schema.org/Person",
      "knows": "http://schema.org/knows",
      "name": {
        "@id": "http://schema.org/name",
        "@protected": true
      }
    },
    {
      "name": "this_attempt_to_override_name_will_fail"
    }
  ]
}

The following would be relevant to add as an example that does not throw an error, even though there is a term override happening:

{
  "@context": [
    {
      "name": "this_attempt_to_override_name_will_fail"
    },
    {
      "@version": 1.1,
      "Person": "http://schema.org/Person",
      "knows": "http://schema.org/knows",
      "name": {
        "@id": "http://schema.org/name",
        "@protected": true
      }
    }
  ]
}

These document was never published, but the specStatus indicates its a WG-NOTE. This causes issues when people look at the ED and see a reference to a non-existing note.

IMO, the group clearly intended to publish this as a NOTE, and it has been referenced. It also gets confused with the former CG note, which it obsoletes. IIRC, the WG is still capable of publishing this as a NOTE, and even with open issues, it should be done.

Noted in discussion on Framing: w3c/json-ld-framing#133 (comment) (w3c/json-ld-framing#133)..

In the interim, the specStatus should be DNOTE (Draft Group Note).

Of note are discussions in w3c/json-ld-syntax#366 and rubensworks/jsonld-streaming-parser.js#65. Best practices should include the principles of JSON-LD streaming, where keys come in a strict order, as well as the use of the streaming document profile so that clients understand the considerations for order of processing when expanding JSON-LD and turning into RDF.

Alternatively, serializations can be limited to a flattened representation so that state does not need to be managed over a large set of embedded nodes (this is probably the most natural way to blindly serialize a large dataset, in any case.

The core JSON-LD API algorithms are intended to work in memory, which is incompatible with the needs of medium to large datasets.

cc/ @wouterbeek @rubensworks

Instead of normatively requiring an initial context, such as RDFa does, instead JSON-LD has the ability to import contexts. This approach means that the existing context rules are followed, and the best practice context can be updated over time as new norms emerge in the community. If the best practice context is not useful to a particular community, then they don't need to import it.

To Do:

• Discuss the set of ontologies to include as prefixes
• Discuss the set of aliases and term definitions to include (e.g. id, type, label, comment)
• Create and publish context document in /ns/

I am not sure why it is there (in §3.6); I have the impression it is a copy/paste leftover...

As I understand the purposes of JSON-LD, one major use case is "semantic lifting", or equipping extant JSON APIs with semantics. ("Zero Edits"). Perhaps it would be useful to include a brief tutorial showing a very simple one- or two-endpoint JSON API and how it can be equipped with semantics just by creating a simple context and adding an HTTP header to the responses.

Given a response object like:

{
	"@context": "https://schema.org",
	"type": "Collection",
	"hasPart": [
	    {
			"id": "123",
			"type": "ScreeningEvent",
			"location": "abc"
		},
		{
			"id": "456",
			"type": "ScreeningEvent",
			"location": "abc"
		}
	]
}

where the Collection is a collection of objects of type ScreeningEvent, should the response include the abc object?

{
	"@context": "https://schema.org",
	"id": "abc",
	"type": "MovieTheater",
	"name": "ABC"
}

If so, what's the best practice for doing so? Would it be best to use an aliased @included ? Or would the initial response be a "Collection of Collections"? If so, should hasPart be an id map? or would it be better to drop that and use custom properties of some kind?

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?

Prefer short idiomatic JSON terms.

Comment on:

We have to be careful: these give the impression that the core constituency for JSON-LD is the linked data crowd. I am not sure this is what we want.

IRIs can be expanded in a few ways depending on their use (e.g. as value or as vocabulary). This is a more-or-less unavoidable inheritance from JSON, but it can be unexpected for some users.

We should give the most clear and straightforward explanation we can of the different bases on which expansion can occur, and how to control each insofar as that is possible.

There have been some discussions on what it would take to be able to do a streaming parse of JSON-LD into Quads, and similarly to generate compliant JSON-LD from a stream of quads. Describing these as some kind of a profile would be useful for implementations that expect to work in a streaming environment, when it's not feasible to work on an entire document basis.

As currently stated, the JSON-LD to RDF algorithm requires expanding the document and creating a node map. A profile of JSON-LD which used a flattened array of node objects, where each node object could be independently expanded and no flattening is required could facilitate deserializing an arbitrarily long JSON-LD source to Quads. (Some simplifying restrictions on shared lists may be necessary). Outer document is an object, containing @context and @graph only; obviously, this only will work for systems that can access key/values in order, and for systems that ensure that @context comes lexically before @graph in the output. Obviously, only implementations that can read and write JSON objects with key ordering intact will be able to take advantage of such streaming capability.

Fo serializing RDF to JSON-LD, expectations on the grouping of quads with the same graph name and subject are necessary to reduce serialization cost, and marshaling components of RDF Lists is likely not feasible. Even if graph name/subject grouping is not maintained in the input, the resulting output will still represent a valid JSON-LD document, although it may require flattening for further processing. (Many triple stores will, in fact, generate statements/quads properly grouped, so this is likely not an issue in real world applications).

Original issue Streaming Profiles for JSON-LD to/from RDF #434.

What is the best approach if one needs to maintain JSON list order, but does not want to use the LISP-like RDF Collections idiom? Should the ordering information be added to the JSON before conversion? Are there any tricks / tools for post-conversion flattening?

The reference [seo-strings-to-things] points to a dead website.
I suggest to use an alternative reference or remove the reference.