Manu Sporny: Dave Longley was implementing this feature and found that the decision we made last week keeps us from implementing something pretty important for PaySwarm. It prevents us from using terms for @ids, so something like this: "rateType": "FlatAmount" isn't allowed anymore, where FlatAmount should expand to http://purl.org/payswarm#FlatAmount

Gregg Kellogg: So, if it's a relative IRI, it's fine, right?

Manu Sporny: We'll it's not a relative IRI, it's a term. The decision we made on the call last week makes it impossible to use a term in @id.

Gregg Kellogg: Ah, I see. I don't agree that it doesn't allow it... we made a decision on syntax, not a decision about semantics.

Niklas Lindström: I think it's an issue, and I thought this might be an issue when we made the decision. We may want a new thing like @symbol (or @term) for this use case. I would not want to revert a decision on @id itself because of the problem with relative IRIs. We did that to stay aligned with the treatment of values in the resource attribute of RDFa. If you want something for type coercion, we need a new keyword that would have the lexical scope the same as what in RDFa is a term or CURIE or IRI.

Gregg Kellogg: I don't see how this is any different from a CURIE, why doesn't it just expand?

Manu Sporny: We already support CURIEs, but we removed terms because of the potential to conflict with relative IRIs.

Manu Sporny: Niklas, I'm confused to how what you're proposing would solve the issue.

Niklas Lindström: Right now, we can do this in the context - "@type": {"@id": "rdf:type", "@type": "@id"}

Niklas Lindström: we could add a feature to do this: "@type": {"@id": "rdf:type", "@type": "@symbol"}

Niklas Lindström: So, you would do something like this in @context: - "rateType": {"@type": "@symbol", "@id": "http://purl.org/payswarm#rateType"}

Manu Sporny: Yeah, downside being added complexity to terms. I think relative IRIs cause more harm than it helps, do we really need them?

Niklas Lindström: I think it's common practice to have IRIs and URLs as relative - they want to put that into JSON and add a context.

Gregg Kellogg: This is done in RDFa and TURTLE and most every other RDF serialization.

Niklas Lindström: RDFa is almost too close - processing terms in JSON-LD in @id is over-the-top for my acceptable-risk level.

Gregg Kellogg: But you're okay with having relative IRIs, you might do resource="#this", that's fine?

Gregg Kellogg: Is it a relative IRI that has a form of a term? Yes. Do we try to protect users from themselves or not? If we try to protect them, there is no end to it. The same argument goes for relative URIs.

Niklas Lindström: If you use a context which defines terms like that, then the risk is there. People won't understand why things are not working until it's too late.

Niklas Lindström: We could do ./ for relative IRIs

Markus Lanthaler: No, that's problematic as well - ./#fragment != #fragment if base is something like ../some/path/file

Manu Sporny: ./ doesn't seem like it would fix all the corner cases. We really need this feature for PaySwarm because developers have said that having colons in things like rateType are confusing. Why can they use colon-less things on the left, but things on the right need colons? It doesn't lead to markup that's easy to understand for beginners. We want this stuff to look as close to the JSON folks use today as we can.

Gregg Kellogg: What about fragment identifiers? What about empty string for relative IRIs?

Gregg Kellogg: I don't think ./ helps. There are a number of things that we can do ./#foo is wrong, "" expanding to "./" is wrong

Niklas Lindström: If there wasn't a heritage for relative IRIs, this would be easier. Web documents have been published with just words (relative IRIs) in href/src for ages. It would be bad to not support it.

Niklas Lindström: The bottom-line is that IRIs are different from terms.

Gregg Kellogg: This seems like a reasonable thing to do in JSON-LD, using relative IRIs.

Markus Lanthaler: Why couldn't you you do this? "rateType": "ps:FlatAmount"

Niklas Lindström: Since we have a distinct lexical scope which we use for predicates and type references, I think a keyword representing that is useful. It's not more complex, it's just explicit.

Gregg Kellogg: Isn't the restriction on using terms just for the value of @id?

Markus Lanthaler: They don't have to know the right-hand side is an IRI - it's an argument for CURIEs...

Gregg Kellogg: Terms are restricted to the value of an @id.

Manu Sporny: No, that's not the problem I don't think. If we have this - "foo": "blah"

Manu Sporny: and we have this in the context: "blah": "http://example.org/vocab#blah", "foo": {"@id": "http://example.org/vocab#foo", "@type": "@id" }

Markus Lanthaler: Keep in mind that "foo": "blah" is equivalent to "foo": { "@id": "blah" }

Gregg Kellogg: That is illegal - the compacted form would be illegal if foo did not have a @type of @id.

Gregg Kellogg: I don't think there is an issue here - you can compact it back down to "blah".

Manu Sporny: That's not the decision I thought we made last week.

Markus Lanthaler: If you type coerce it to @id, isn't that equivalent?

Niklas Lindström: So, you're saying this is illegal if "blah" is a term? "foo": {"@id": "blah"}

Gregg Kellogg: Semantically, they mean the same thing - syntactically, it's illegal.

Gregg Kellogg: It'll compact back to just using "blah" if "foo" has a @type of @id. If it didn't have a @type of @id, it would compact back down to a node reference and you couldn't compact it back down to blah.

Gregg Kellogg: If foo was defined with xsd:integer, you wanted to use foo - you would have to use the long form - the object form for the IRI.

Manu Sporny: So, two things going on here syntax vs. semantics. When we make the rule that a term cannot be put in the value of @id, we're talking about the syntax - not the semantic meaning.

Gregg Kellogg: I think this solves this conundrum - there really isn't a problem.

Niklas Lindström: I think we disabled it for @id because a relative IRI could be mistaken for a term or vice versa. I think the value of a property, even if it is type coerced to @id, when you process it you process it as @id, I don't think we can distinguish it when processing.

Markus Lanthaler: I dont' think that's the decision we made.

Niklas Lindström: What's difference between "foo": {"@id": "blah"} versus "foo": "blah" where foo is coerced to @id ?

Gregg Kellogg: When I voted on this, I thought it was a syntactic restriction - if it wasn't, I would change my vote.

Manu Sporny: When I voted for it, I didn't realize we were introducing this limitation.

Markus Lanthaler: Wouldn't a simple technical solution be to just compact to a relative IRI if there is no term that collides.

Markus Lanthaler: It might not be a good idea, but it would be easy to debug.

Niklas Lindström: I don't know if I like that.

Manu Sporny: I'd be fine with it, Dave Longley didn't like that.

Gregg Kellogg: This is a short-hand for the same syntactic construct...

Niklas Lindström: The problem remains... which is accidentally introducing bad data.

Manu Sporny: Two potential solutions here - what Niklas proposed, and adding 'term' back into the allowed types for @id (which could lead to uncompated IRIs). It doesn't seem like we're close to consensus and we've burned through 40 minutes of telecon time. Any objections to move on in our Agenda? We should discuss potential solutions in the issue tracker.

Manu Sporny: We had general agreement that this isn't an issue.

Markus Lanthaler: The question is whether or not we take the default language into account when applying a term - the algorithms are written this way. Perhaps we should add a sentence or two to the syntax spec to make this clear.

Gregg Kellogg: I think the spec is clear, let's close this issue.

Manu Sporny: I don't know how much headway we can make on this.

Gregg Kellogg: My concern is that things need to be easy to understand in the spec, so let's table this until Dave makes more progress.

Manu Sporny: Dave's been busy reading both Markus' and Gregg's updated algorithms. He is implementing most of it, but introducing his own algorithms for the things that could be simplified. He will update the spec text when he is done.

Manu Sporny: general approach of dave's algorithms is to simplify and ensure that there is a prose header that accurately describes the inputs and outputs of the algorithms. [scribe assist by Gregg Kellogg]

Gregg Kellogg: … He has a simplified version of reverse contexts that should be easy to use.

Gregg Kellogg: … He also plans to run with Markus' restatement of term selection, which had broad support.

Manu Sporny: probably not going to make Last Call (LC) by end of January for the JSON-LD Algorithms and API. [scribe assist by Gregg Kellogg]

Markus Lanthaler: can we change the algorithms after we're in last call? [scribe assist by Gregg Kellogg]

Manu Sporny: it's a gray area. We could enter into LC and then modify the algorithms, but if they change some corner-case that would make it a big change, causing us to go through another LC. [scribe assist by Gregg Kellogg]

Markus Lanthaler: When can we go to LC?

Manu Sporny: At any time, really - when we're ready. What we should make sure is that all of the editor's are on-board with the algorithms before going to LC. If we don't do that, we increase the risk of having to go through another LC. So, better to put off the LC than go into it prematurely.

Gregg Kellogg: I think the RDF WG was just concerned about making sure that we're really close to LC, for the extension of their charter. We're very close with the API spec, so let's wait for Dave's changes and go from there.

Manu Sporny: I went through the spec with a fine-toothed comb and fixed a number of editorial issues. I've done Sections 1-5, Advanced section is next. There are a few problems with the spec at this point: 1) we use some terminology before we define it, 2) we introduce some concepts in the basic section that should be in the advanced section. Overall, I think the flow of the document has suffered by consolidating sections.

David I. Lehn: after looking at recent commits, you all might want to coordinate a common whitespace, indentation, and html style.

Manu Sporny: I think that's the least of our worries. These documents go through so many edits that it's difficult to keep that stuff well organized. We can do a code-formatting run after the docs are out of Last Call or Candidate Rec.

Gregg Kellogg: We do want to be consistent with words - for flow, most of us are used to reading these things in a browser, so you can go back-and-forth easily enough for the terminology issue... unless there are people that print these specs out to read them.

Markus Lanthaler: The other problem is that sometimes we have to repeat things, so we should consolidate

Markus Lanthaler: It would be simpler to combine certain sections into a single section.

Manu Sporny: I am strongly against combining some of the sections in the way they've been combined. It used to be that you would get a very gradual introduction to the JSON-LD, that is no longer true for the spec, and that's a very bad thing. There are some things in the basic section that need to be moved to the advanced section, they are too much for a first-time reader to grasp.

Gregg Kellogg: I think there are two issues here - one is editorial coordination, a need for us to communicate before we make big changes unilaterally.

Gregg Kellogg: There might be a little more harmony if we discuss an approach together and proceed on that general approach. The second is the specifics of this, the form of the syntax document.

Gregg Kellogg: I think it had a pretty nice flow before all the way up to advanced concepts, if that means simplifying examples, then that's good.

Paul Kuykendall: I hope I'm not speaking out of turn, but as a newcomer to reading the JSON-LD specs, I agree with what Manu is saying regarding the spec hitting with advanced topics right off and explaining things far later in the document.

Gregg Kellogg: I think we should leave the more nasty details to section 6.

Gregg Kellogg: Paul, that's good input.

Gregg Kellogg: One of the things we're trying to convey is that an important part of JSON-LD is that it's simple... we should keep it that way in the beginning of the spec.

Manu Sporny: I also don't like that we've chipped away at the Design Goals and Rationale section. We've gotten rid of the stream-based processing bit. That's a shame, we should try to say what it said before in a way that works for everybody.

Manu Sporny: Specifically, I think these examples need to move to the advanced section: example 1 should be simplified, that would simplify example 2. Example 6, 7, and 8 should all go in the advanced section. Section 5.1.1 should go to advanced. Example 12, 13, and 16 should go to advanced. String Internationalization could go to advanced.

Markus Lanthaler: I don't want Link relationship example to be moved to advanced concepts.

Markus Lanthaler: I also don't want @vocab overriding moved to advanced.

Gregg Kellogg: I don't agree - overriding is more advanced of a concept.

Niklas Lindström: I agree.

Niklas Lindström: Prefix expansion could be in Basic... but perhaps not - I could go either way.

Gregg Kellogg: I think the simple use of JSON-LD is using terms and not CURIEs.

Niklas Lindström: true

Manu Sporny: The advanced section is okay with the flow, I guess. Some of them are difficult to compare - how should we introduce them, in what order?

Niklas Lindström: If it's hard to compare the relative difficulty of advanced concepts, then perhaps having to introduce them in the same order as the basic section would be good.

Markus Lanthaler: Should Data Model and JSON-LD Grammar be appendixes since they're normative?

Manu Sporny: I like them as an appendix.

Niklas Lindström: Yeah, they could be a normal section.

Gregg Kellogg: I think the consensus was that there was no problem with having a normative appendix.

Markus Lanthaler: It looks weird if all normative statements are in an appendix.

Gregg Kellogg: This is supposed to be the primary entry point for folks - that's why it's in an appendix, I think it works pretty well, other than having the issue of term definitions.

Gregg Kellogg: Some people may print this out and try read it.

Paul Kuykendall: The Data Model and Grammar sections also end up having lots of definitions that are almost required to understand the concepts from the earlier sections. Having some reference in the terms section to point there would be helpful

Paul Kuykendall: By the way, I print the specs so can write on them.

Manu Sporny: I'm always hesitant to have these sorts of discussions too often, but it came up because the Editor's agreed to move Mark Birbeck's name from the Author section to the Acknowledgements section and give him a few sentences thanking him for RDFj (which spurred the JSON-LD work, some of which is based on RDFj concepts). Markus also moved Dave Longley to the end of the Author's list for the Syntax spec, which was a big problem.

Manu Sporny: I think Markus was looking at this when he made the decision: https://github.com/json-ld/json-ld.org/graphs/contributors

Manu Sporny: I don't think making authoring/editorial decisions based solely on number of commits is a good idea. I think all of us have a pretty good feeling for who contributed what and how much, so this discussion is to try and come to a consensus about that.

Manu Sporny: Ownership over anything is always dicey and can create bad feelings. We want to be fair to everyone, most people value their contributions more than others because they know what went into their contributions. Some folks are better at asking for recognition than others, some are too generous, others not so much. So, that's why we need to have the discussion - to pick an order that is fair. This is the current order:

Manu Sporny: Any thoughts before I present an ordering?

Gregg Kellogg: I think that Markus has done a great deal of work, and I'd be happy to switch with him on the list. I also want to make sure my contribution is recognized. There is more to putting these specs through the process than just writing them. You need to know what to write, what to change, what not to write, implement, manage expectations with other groups, coordinate, bug triage, think deeply about the problem, etc.

Gregg Kellogg: Manu, you have the most spec experience. This is a charged thing, I want to be known for the contributions I made to this, but also want to be fair to all.

David I. Lehn: there is always the fallback to alphabetical order

Manu Sporny: I abhor alphabetical order because I think it's about as unfair as you can get when listing contributions to a particular document. Many of us have put in hundreds of hours into this specification, to list people alphabetically is just wrong. We should identify who did the most work, gather consensus around it, and that should be the order. That is what's fair.

Manu Sporny: The proposal is to keep the authors in the JSON-LD 1.0 syntax as is, as that reflects reality.

Manu Sporny: The proposal for the JSON-LD Algorithms and API spec would be Editors: Markus, Gregg, and Manu. Authors: Dave, Gregg, Markus, Manu

Niklas Lindström: +1

Gregg Kellogg: +1

Manu Sporny: +1

Markus Lanthaler: +1

Manu Sporny: Then that's settled and wasn't nearly as painful as I was dreading. Good to know we're all on the same page. We have to make the acknowledgements section better - definitely for Mark. We need to add Ivan and Stephane as well (and Lin if she's not already on there).