Some initial feedback

[rubensworks]

I just went through all of the markdown documents in this repo. This issue lists some feedback. Feel free to ask for further clarification on anything. Happy to look at it again at a later stage.

README

Intro

While the description on the top of the page is understandable to me, I'm afraid that it might not be immediately clear to readers that don't work with hypermedia that much.

One alternative attempt of a description (feel free to ignore :-) ):

TREE Publish data on the Web while enabling the exploitation of relationships between literal values

For publishers: Publish literal relationships within your dataset via hypermedia. For query agents: Discover relationships between data to know whether or not to follow links.

Would it make sense to add a simple diagram figure right after the description? For example, something showing a page with some members, and a pointer to a tree that shows how the members are ordered.

The Vocabulary

I'd add an example here of how these important concepts are used.

Specifications

must -> MUST. (also applies to other files)

Vocabulary

tree:Relation

Perhaps something for future work: I can imagine that there is an infinite number of possible relation types. To avoid having to implement each one of them separately in a query engine, it might make sense to describe this relationship at the ontology level in a declarative manner, so that an engine could automatically deduct that tree:LessThanRelation === int < int.

1-discovery.md

Formally

there must be a property linking the current page URL to the URI of the tree:Collection

To make it easier for implementors, I would suggest making one of these properties a MUST, and the others a MAY. (No strong opinion on this though)

I would add some more words explaining what currentPageUrl exactly is. These things are important:

• The RDF spec says that IRIs must be compared character by character. This means that the document that the server returns for a given URL MUST contain exactly the requested URL (after redirects). For example https://example.org/ !== http://example.org/.
• Encoded characters should not be expected to be handled by the client, this is something the server should do.
• Fragments (#) are never sent to the server, so this currentPageUrl can never contain any.

Compliance testing

would it make sense to make the last query an ASK query?

Future work: might make sense to set up a service where people can just enter a URL, and they get a conformance report back as output. (similar to those HTTPS validators)

2-traversing.md

I would add some short examples here, as it's quite hard to imagine what all of this should look like when reading this document.

The object of tree:value should be accompanied by a data type when it is a literal value.

In RDF 1.1, literals always have a datatype. It defaults to xsd:string. Is this valid here as well? Or do you mean that xsd:string are not allowed? And what about language-tagged strings?

an example of how to use a qualified value can be viewed here

Even with the example, I don't really understand what this is exactly.

Comparing strings

SPARQL regexes came to mind while reading this. Could these comparisons be expressed in terms of SPARQL regexes? This may also make compliance checking easier.

Comparing geospatial features

The tree:path must refer to a literal containing a WKT string, such as geosparql:asWKT.

... only if geospatial features are used.

Comparing time literals

There are other date-related datatypes as well that are sometimes used in RDF. Do you want to support those? Such as gDay, gMonthDay, gYear, gYearMonth, ...

3-search.md

At the moment, I don't get the aimed difference with the previous documents. But I suspect this is still a WIP.

[pietercolpaert]

Thanks for the thorough feedback. I think most of it was tackled in the new reviewed spec at https://treecg.github.io/specification.

Only point still open is on comparing strings. @hdelva is going to open a pull request extending that chapter. I don’t entirely get your suggestion on SPARQL regexes though. Could you draft a proposal for that?

[rubensworks]

I don’t entirely get your suggestion on SPARQL regexes though. Could you draft a proposal for that?

(SPARQL) regexes may for some people be easier to understand. For example, tree:PrefixRelation for "abc" is equivalent to the SPARQL regex "^abc".

This would also be useful for test suites, where the results of this prefix relation should be equivalent to:

SELECT ?nodes WHERE {
  ?s ?p ?o.
   FILTER regex(?o, "^$PREFIX$")
}

But that's just a thought I had when reading the spec. I think the text is sufficiently clear without it in any case.

[pietercolpaert]

Thanks! I’ll close this issue then!