Sandro's feedback

Here are the things that I think need some discussion.


>  > A number of design goals were established before the creation of
> this markup language:
> 
> I don't think the history matters.
> 
> How about: JSON-LD satisfies the following design goals:
> 
>  > language. We should focus on simplicity when possible.
> 
> I don't think that's what you mean. I think you mean simplicity is
> paramount.
> 
> How about: to the language, so sometimes we do not achieve Zero Edits.

What about dropping this section entirely?


>  > Conformance
> 
> SERIOUS
> 
> It's somewhat odd that all one needs for conformance is appendix B.
> So what are the other normative parts of this document for...?
> 
> I think there may be a notion of a conformant JSON-LD generator or
> parser here, too -- one that follows the rules of the rest of this
> spec. That should be stated here.

Not sure about this one. We deliberately tried to keep these two things
separate.


>  > a context is used to map terms, i.e., properties with associated
> values, to IRIs.
> 
> Uh, that doesn't match the definition in #dfn-term. Is a term really
> a property with its associated value? I don't think so.

You are right. I removed it for the time being. We need to explain where
terms can be used in more detail here. 


>  > EXAMPLE 5
> 
> after this example I was expecting the next example to use a Link
> header
> (what turns out to be EXAMPLE 29). Maybe mention it here?

I completely agree. I also think that that feature is very important for
adoption so I would really like to put it to the front and not hide it
somewhere in the. We already discussed this in the group but people felt it
is too early in the document. Maybe we should revisit it.


>  > JSON keys that do not expand to an absolute IRI are ignored, or
> removed in some cases, by the [JSON-LD-API]. However, JSON keys that do
> not include a mapping in the context are still considered valid
> expressions in JSON-LD documents-the keys just don't expand to
> unambiguous identifiers.
> 
> This is kind of weird. It doesn't tell me what I'm supposed to do; it
> just confuses me.
> 
> I guess it means they're like comments, and to be ignored?
> 
> This is where we need a clear notion of a processor that reads JSON-LD
> and extracts all the triples and quads from it, it seems to me.

That's a tricky question. The thing is that we allow keys in JSON objects
which do not expand to IRI and would consequently produce no triples. We
didn't want to restrice the behavior completely. Some processors might find
it useful to keep those things even after expanding.. our official expansion
algorithm drops such properties.


>  > To be able to externally reference nodes in a graph, it is important
> that each node has an unambiguous identifier. IRIs are a fundamental
> concept of Linked Data, and nodes should have a de-referenceable
> identifier used to name and locate them. For nodes to be truly linked,
> de-referencing the identifier should result in a representation of that
> node. Associating an IRI with a node tells an application that it can
> fetch the resource associated with the IRI and get back a description
> of the node.
> 
> I'm not a fan of this paragraph. Can we just delete it?

I don't feel strongly about it but I think we should keep at least parts of
it. What do others think?


>  > 6.3 Type Coercion
> 
> MEDIUM
> 
> Okay, this overloading of @ keywords goes too far with @vocab serving
> a completely different purpose (from normal @vocab) in this
> situation. That's just silly.
> 
> Maybe we could at least have a table showing what how the meanings
> differ in different places in the structure.

Yes, that's a really advanced feature. We should discuss how to explain
these things better.



> (glancing at appendix B for something)
>  > To avoid forward-compatibility issues, a term should not start with
> an @ character
> 
> MEDIUM
> 
> Why only SHOULD NOT? Why not MUST NOT? The damage if they do is
> considerable.
>
> Also, you kind of need to say what processors MUST do if they see a
> keyword term they don't know -- ie one from the future. The options
> are: ignore (if you can figure out what/how much to ignore); or halt;
> or issue a warning to the user.

I would be fine with changing it to MUST NOT.


>  > 6.11 Embedding
> 
> Odd section. It seems to have forgotten this was introduced as a
> graph syntax. The main thing to highlight is that this is syntactic
> sugar; sometimes it's nice to syntactically embed the node in one of
> the places that had a link to it.

Would be fine with dropping it


>  > The JSON-LD Algorithms and API specification [JSON-LD-API] defines
> the conversion rules between JSON's native data types and RDF's
> counterparts to allow full round-tripping.
> 
> SERIOUS EDITORIAL
> 
> I really don't like the mapping-to-RDF being left to another, later
> spec. I can live with it just being shown in the examples, except for
> not knowing what happens with numbers. From the playground I see
> integers end up as xsd:integer and otherwise they are xsd:double,
> which is simple enough, but should really be said in this document, or
> at least shown in an example.

I would be fine with adding such information. Maybe just pulling in the
first paragraph from

http://json-ld.org/spec/latest/json-ld-api/#data-round-tripping 

would be enough!?


Cheers,
Markus



--
Markus Lanthaler
@markuslanthaler

Received on Thursday, 7 March 2013 00:24:56 UTC