Definition of JSON-LD processor in the API spec #184

Closed
tidoust opened this Issue Nov 7, 2012 · 12 comments

Projects

None yet

5 participants

Contributor
tidoust commented Nov 7, 2012

[Moving out that part of the discussion from #166 to its own issue]

Context

As part of a Conformance section proposal (#166), I drafted a definition of a JSON-LD processor as one class of product that implements the Syntax doc.

The current definition is:

A JSON-LD processor parses a JSON-LD document and generates the corresponding JSON-LD graph (mapping terms to IRIs and coercing values). A JSON-LD processor complies with this specification if it follows the normative statements for processors. Statements that are applicable to a JSON-LD processor are identified in this document by use of the term "JSON-LD processor" in the singular or plural.

Problem

Gregg notes that the JSON-LD processor actually creates a JSON-LD dataset (whose definition is being discussed in issue #182) rather than a JSON-LD graph.

I add that it seems to me a JSON-LD processor is something that implements the algorithms and API of the JSON-LD API spec, meaning something like:

A JSON-LD processor parses a JSON-LD document to create a JSON-LD dataset according to the expansion algorithm defined in [JSON-LD API]. It exposes the API defined in [JSON-LD API] to transform the JSON-LD dataset following the algorithms defined in that document.

The definition affects how the document phrases statements on JSON-LD processors.

In essence, if the behavior of JSON-LD processors noted in the JSON-LD Syntax document directly follows from implementing the algorithms defined in the JSON-LD API, the JSON-LD Syntax spec should simply defer to the JSON-LD API for normative statements that JSON-LD processors need to follow. If that's the case, a JSON-LD processor is actually not a product that implements the JSON-LD Syntax doc and its definition should also be removed from the Conformance section.

If normative statements on JSON-LD processors are actually needed, then how do they relate to the algorithms (the expansion algorithm in particular since it's the one that's closest to a "parsing algorithm") defined in the JSON-LD API?

Proposals

I'm inclined to think that a JSON-LD processor is a class of product of the JSON-LD API spec and not a class of product of the JSON-LD Syntax document. I suggest the following proposal:

PROPOSAL: In the JSON-LD Syntax document, define a JSON-LD processor as a product that implements the JSON-LD API, noting its purpose is to create a JSON-LD dataset. Drop all normative statements that apply to JSON-LD processors from the JSON-LD Syntax, ensuring that they are covered by the algorithms defined in the JSON-LD API.

(the discussion on referring to JSON-LD dataset is somewhat orthogonal to this one)

@tidoust tidoust pushed a commit to tidoust/json-ld.org that referenced this issue Nov 7, 2012
François Daoust Markus feedback on recent Conformance/Grammar updates incorporated.
- Created issue #184 to discuss the definition of a JSON-LD
processor. The doc references that issue in the meantime.
- Incorporated Markus feedback to clarify when a JSON object with
a null value is ignored
- Re-introduced statement that discourages the use of empty terms
in "Context" section. I left it in the grammar as well because that
also seems the right place to mention it but, technically speaking,
it could be removed from there since it's not a normative binding.
0cabdac
cygri commented Nov 7, 2012

How about moving JSON-LD processors to the Conformance section of the JSON-LD API spec? This seems especially appropriate if that spec is renamed to “JSON-LD Processing” or something similar. My (possibly incorrect) hunch is that the Syntax spec can be largely silent on processors, and that all normative statements applying to processors can easily be moved to the API spec.

Contributor
tidoust commented Nov 7, 2012

+1.

For clarity, note that's exactly what my proposal suggests in a more convoluted way:

  • define "JSON-LD processor" in a Conformance section in the JSON-LD API
  • drop all normative statements that apply to JSON-LD processors from the JSON-LD syntax doc, or move those that are not covered by the algorithms to the JSON-LD API doc
  • refer to the JSON-LD API doc when JSON-LD processors are mentioned in the Basic Concepts and Advanced Concepts sections in particular. Or stop talking about JSON-LD processors, but my gut feeling is that it remains very useful to explain how the JSON-LD dataset is created from a JSON-LD document.
Member

+1 to what you outlined above, specifically

PROPOSAL 3: Define "JSON-LD processor" in a Conformance section in the JSON-LD API

PROPOSAL 4: Drop all normative statements that apply to JSON-LD processors from the JSON-LD syntax doc, or move those that are not covered by the algorithms to the JSON-LD API doc

I would like to change the last statement above to

PROPOSAL 5: Update the JSON-LD syntax specification to not use the term "JSON-LD processor".

I just checked, it should be a rather trivial change.

Owner
gkellogg commented Nov 7, 2012

+1 to all those, we should continue to have an informative reference to the API/Processing document, though.

Contributor
tidoust commented Nov 7, 2012

OK with the PROPOSAL 5 update (and ok with proposals 3 and 4, of course).

I'm fine keeping an informative reference to the API doc for the time being. I'm worried that reading the syntax doc, the reader cannot easily determine how a JSON-LD document translates to a JSON-LD graph/dataset and/or that the "Basic concepts" and "Advanced concepts" sections actually describe things that depend on how the algorithms are specified. That depends on how the doc gets updated, so I'll try to articulate my concerns later on once that is done, if needed.

@tidoust tidoust pushed a commit to tidoust/json-ld.org that referenced this issue Nov 8, 2012
François Daoust Removed definition of JSON-LD processors from the Conformance section
Other sections still mention JSON-LD processors, either to describe
how JSON-LD documents are processed or to put constraints on JSON-LD
processors through normative statements. Descriptive text would need
to link to the proper definition of JSON-LD processor in the API doc.
Normative statements that apply to JSON-LD processors need to be
dropped. All of this is being covered by issue #184.
f9f1b65
Member

PROPOSAL 3: +1

PROPOSAL 4 and PROPOSAL 5 have been obseleted by François' PR #194.

@msporny msporny closed this Nov 20, 2012
@msporny msporny reopened this Nov 20, 2012
Owner
msporny commented Nov 20, 2012

PROPOSAL 3: +1

Member

I renamed the issue from "Definition of JSON-LD processor in the Syntax doc" to "Definition of JSON-LD processor in the API spec".

Member

RESOLVED: Define "JSON-LD processor" in a Conformance section in the JSON-LD API

@lanthaler lanthaler added a commit that referenced this issue Dec 3, 2012
@lanthaler lanthaler Add conformance section to JSON-LD API spec
I also added statements to all algorithms saying that they expect well-formed JSON-LD documents.

This addresses #184 and #188.
def0f68
Member

I've added a conformance section in def0f68 to the JSON-LD API spec. Could all of you please have a look at it so that we can briefly discuss it in tomorrow's telecon.

Thanks

Member

RESOLVED: The JSON-LD API specification will define two products: 1) A JSON-LD Implementation, and 2) A JSON-LD Processor, which is dependent on a valid JSON-LD Implementation and implements the asynchronous API.

Member

I updated the API spec. Unless I hear objections I will therefore close this issue in 24 hours.

@lanthaler lanthaler closed this Dec 5, 2012
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment