Expansion/Compaction explanation inaccurate or misleading

[dlongley]

Sections 6.15 and 6.16 of the syntax spec aren't quite accurate in their descriptions of expansion and compaction. The language is probably just a remnant from earlier confusion over the purpose of expansion and compaction.

6.15 states:

"Expanded document form is useful when an application has to process input data in a deterministic form. It has been optimized to ensure that the code that developers have to write is minimized compared to the code that would have to be written to operate on"

Expansion is about removing context and regular form (which 6.15 states earlier and is fine) but it does not necessarily result in something that is "optimized" for developers. Expanded form is less optimal for many developers and may actually be the less common choice for developers. Rather, they may prefer to have something compacted according to a context their application expects. In fact, the statement above seems to be in conflict with a statement made below about compacted form being optimized for applications.

6.16 states:

"Compaction is the process of taking a JSON-LD document and applying a context such that a very compact form of the document is generated. At times, a JSON-LD document may be received that is not in its most compact form."

Compaction is not about getting a JSON-LD document into its "most compact form," but rather it is about compacting a JSON-LD document down from expanded form into a form that is to be expected based on a given context. It is about getting contextual information out of the way because it's already known via some other means. A "compression" algorithm would likely do something different -- and the result isn't meant to be operated on (or well-understood by reading), but rather it is typically just used for transport. This was a point of confusion early on due to the name choice, but now that we're essentially stuck with it, we definitely need to ensure that we don't cause this misconception to proliferate.

The API spec language has been updated to better explain expansion and compaction and maybe some language could just be cut and paste (with minor changes) from there to replace the spec in the syntax spec.

[lanthaler]

I agree. As a first step, I removed the confusing statement from 6.15 which didn’t say much anyway.

What about changing the intro of 6.16 to

“The JSON-LD Algorithms and API specification [JSON-LD-API] defines a method for compacting a JSON-LD document. Compaction is the process of applying a developer-supplied context to shorten IRIs to terms or compact IRIs and JSON-LD values expressed in expanded form to simple values such as strings or numbers. Often this makes it simpler to work with document as the data is expressed in application-specific terms. Typically compacted documents are also easier to read for humans.”

I think we should also add some info about flattening because that really creates a deterministic shape for arbitrary data. Probably compacted flattened form is easier to understand. We can then mention that it is of course also possible to have expanded-flattened.

[dlongley]

That paragraph looks good. Just needs a comma after "Typically" in the last sentence ... or just change it to: "Compacted documents are also typically easier to read for humans."

I don't know about mentioning flattening; I don't feel too strongly about it either way. I don't know that it's necessary, but if it can be done without introducing too much for people to consume that might be ok. I'll defer to others.

cc: @msporny, @gkellogg, @niklasl

[lanthaler]

OK I’ve updated the spec and since Charles Greer also requested that we include a section mentioning flattening I added that in 0111ecb. I think this resolves this issue. Unless I hear objections, I will close this issue in 24 hours.