link-guidance.html final editing issues

[oslc-bot]

1. Anchor: a link plus information that annotates or labels that link for use when a relationship must be annotated with property-values.

Anchors are done through reification using an ref:Statement with subject, predicate and object and rdf:ID for the assertion being annotated, and any additional properties required.

Additional guidance should discuss that properties on links possibly indicate missing classes in the vocabulary and associative objects could be used to model the link properties more directly.

2. Examples should be in Turtle and, there is no OSLC Core JSON format (Turtle only)

3. Anti-pattern in section 3 referes to OSLC query syntax which isn’t supported

4. Include guidance on storing the link information in one place and utilizing queries to traverse the link in both directions. i.e., no inverse properties or bi-directional links.

---

Migrated from https://issues.oasis-open.org/browse/OSLCCORE-18 (opened by @jamsden; previously assigned to @jamsden)

[oslc-bot]

@jamsden: I have address these issues and created a new version.

[oslc-bot]

@neocolmartin: Reading through the latest versin of the document from jra-editing, and these are my comments:

A. §2.1 Link: "when... you don‘t want to inline any summary of the target". My understanding is that anchors shoudn‘t be used to inline values of the target. RDF already allows you to do that, by including another triple whose subject is the target (that is, object) of this link (triple). Anchors should only be used to describe the relationship itself.

B. §2.1 Link: "In OSLC, you express a link as a property with OSLC value-type of Resource and OSLC representation of Reference. For example..." I know this is referring to the values that we used (at least in v2) in the resource tables. Are we still using them in v3? Are they also the terms used in resource shapes? We ought to be more clear about why this information is useful to the reader. I‘m not sure it is. And the following example doesn‘t relate to this sentence at all, but to links in general. Simplest fix: remove this sentence. Alternatively, start the sentence with "In OSLC resource tables, a link is expressed as...", and move it after the example.

C. § "Don‘t make assumptions about the target of links". Should this be §2.1.1? Also "Store link information in one place" §2.1.2?

D. § "Store link information in one place". This is a little ambiguous as there are (or could be) two issues in play here:
1: Reverse links
2: Duplicated triples.
Reverse links have very much been identified as an anti-pattern. That is, A ex:affects B and B ex:isAffectedBy A. The "isAffectedBy" predicate should not exist (and therefore not be used). (Or at least only one of them should exist, sometimes a "...By" link might be correct to be the only direction that exists).
Duplicated triples have the same problem as any redundancy, and should be avoided when not needed, but in my mind are the right way to go when you need redundancy. e.g. a request to A might return "A ex:affects B", and a request to B might return "A ex:affects B". If they are on different servers then B‘s representation might get out of date, but the client should be able to tell that this is from a non-definitive source as the subject‘s URI has a different host/port than the request URI.
The word "storing" suggests the latter to me - which resource is it returned from (presuming a resource-based storage mechanism such as a document database), but the test appears to talk only about which is the subject of the triple. We should probably address both, strongly speaking against inverse properties, and suggesting that any redundancy of triples is treated with care.

E. Anchor section looks good to me (after your edits).

F. §3: "When you link to a target resource that has a dcterms:title value and you inline that dcterms:title in the subject resource, in the RDF data model this means that you have just given the object resource two titles." Is this really true? My understanding is that if two triples match exactly then they are the same triple. I can‘t cite a source for that off the top of my head, but neither does this document cite a source. I presume (like with most of my comments here) it‘s something we‘ve inherited from v2.
In RDF terms I see no difference between example 6 and example 7 - I expect them to result in exactly the same triples. (Indeed when we move this to Turtle, I think there will be no difference between those two examples).
As already stated, we should suggest care when introducing redundancy, but sometimes it is needed, and it should be done in the correct RDF way, and to me the anti-pattern is duplicating that information in different triples, i.e. in triples on an anchor.

G. I didn‘t see anything in the latest version about point 4 in this ticket‘s description.

[oslc-bot]

@ndjc: With regard to including triples about the target of a link - this has security issues as well as coherence issues, and in general should not be recommended. For example, the name or label of the target of a link SHOULD NOT be included in the RDF representation of the source of the link, because the user reading that source resource might not have access to the target resource, and the name itself might contain secure information. In extreme cases, the very existence of a link might be considered as information that should not be revealed unless you have access to both ends, but in most cases this degree of hiding is not necessary.

[oslc-bot]

@jamsden: re: A. Are you suggesting to just remove "you don‘t want to inline any summary of the target" from that sentence?

re: B. I think we should clarify the sentence. This is related to how ReSpec uses the shapes files to generate the properties. The meaning of the columns in the property table need to be defined somewhere. Nicks text could be included too.

re: C. Since this is informative and a Committee Note, maybe these additional sub-sections aren‘t needed?

re. I can expand on this section.

re:F. I think this meant to say that you have potentially included the title property in two places in the RDF/XML, one inlined, and possibly another that isn‘t inlined - and they could be different.

re: G. See you D. Isn‘t this it?

[oslc-bot]

@neocolmartin: A: Yes, to just remove that bit.

B: Quick suggestion as to clarification: "For example, here is a property terms:subscribesTo that you might find inside a customer resource, it links to a resource that is "subscribedTo" by the customer: (example here) ¶In RDF terminology, a link is called a URI Reference.¶In OSLC specifications‘ resource tables, a link is expressed as a property with OSLC value-type of "Resource" and OSLC representation of "Reference"."

C: I think it‘s useful to have the headers break the text up, and if we have headers they might asw well be numbered.

F: If we change the examples to Turtle, I believe that there will not be two locations.

G: I think the thing from point 4 that I felt was missing was "utilizing queries to traverse the link in both directions". The text just says "using a simple query", but it‘s not neceserily simple to know where or how to query, especially if the other resource is on another server. Especially as at v3 we don‘t have a single query format to rely on. Perhaps we need a "querying guidance" doc or section somewhere (which we can update once LDP querying gets sorted), which we can link to from here.

[oslc-bot]

@neocolmartin: Re: Nick‘s comment.
I expect that security issue applies mostly to triples whose object is not a URI. For links, whose objects are always URIs, while there could be some restricted information in the target‘s URI (which to me would suggest a misconfiguration or misuse of the target server), it should less of a security issue to include that triple in the object‘s representation than triples with textual objects, so I expect "this degree of hiding is not necessary" with all links.

[oslc-bot]

@jamsden: A: removed the text: you don‘t want to inline any summary of the target

B: This is referring to the oslc:ResourceShape Resource in OSLC 2.0, and the columns of the tables in the Resource Constraints sections. But oslc:representation is only used in the Comment (creator and inReplyTo) and Discussion (comment) shapes, and does not appear in the generated table in OSLC 3 specs. Looks like there was a decision to not indicate whether a representation is in-lined or a URL. This is still in section 6.2.2 of the Resource Shape 2.0 member submission.

Note Comment property inReplyTo has oslc:valueType oslc:Reference - it should probably be oslc:Resource. These shape .ttl files were created for OSLC 3, so this is likely a typo.

C: Added the clause subsections, and labeled the examples

D: expanded the section and included much of Martin‘s text

F: There are two assertions about the title, and they could have different values. Clarified that section.

G: Added some text about using queries using subject or object to navigate the relationship in either direction so the inverse property isn‘t needed.

[oslc-bot]

@neocolmartin: A. Have these changes been committed yet? I presume not, as I still see that text (looking at "jra-editing" branch).

B. Can anyone find any record of this decision? Might this cause problems for v2 clients if they‘re relying on v2‘s requirement for a target to be inline? Although I expect the value-type of Resource vs LocalResource should address that.

Can‘t comment on other points until the changes are in.

[oslc-bot]

@ndjc: At least in Configuration Management, we do require that some resources are returned inline. The resource type does not adequately define that: Resource is expected to be a reference in most cases, LocalResource is one that cannot be a persistent URI (must be a blank node or hash URI), and AnyResource can be either, but does not imply it must be inline. So I think we still need the extra column, and that its absence is a deficiency of the current ReSpec Javascript. I‘d like the Javascript to generate the column IF any of the properties in the shape use a value other than a default of oslc:Reference.

[oslc-bot]

@jamsden: I‘m trying to commit today, maybe tomorrow.

Regarding B: we can search the meeting minutes, but I suspect the removal of the oslc:representation may be related to the Link Guidance "Link with in-lined values of target anti-pattern. If you‘re using RDF, and not XML DOM or XPath to parse the RDF/XML or Turtle, then it shouldn‘t matter whether the statements are in-line or not.

[oslc-bot]

@ndjc: I think inlined resources and inlined values of target attributes are orthogonal issues. Yes, we agreed inlining values of attributes of the target of a link is an anti-pattern. However, there are good reasons why we sometimes want to to require inlining an entire resource. One reason is efficiency; if a resource (such as a configuration) has a potentially large number of small dependent resources (the contributions) which are separate only in the RDF subject sense, but really part of one data structure, you want to have that structure returned in one HTTP resource. Another reason is to remove the need for server persistence. Suppose you have a resource that describes the multiple possible matches for a concept resource in a global configuration. If you do not return this inline with the resource itself, the server would have to persist the possible matches for some indeterminate length of time - and might have to do so for multiple GET requests for the same concept resource, since the version matches may change quickly over time. Having the matches returned inline in the same HTTP resource (same REST request) avoids the issue.

[oslc-bot]

@jamsden: I don‘t have any problem with servers creating efficient resource representations. What concerns me is when we standardize on a particular resource representation because we think its the best for a specific purpose, and it turns out to be less ideal for future usages we didn‘t anticipate.

Servers should be free to send any representation of a resource they want, inlined or not, as long is it is a valid RDF representation. Clients should not depend on any particular representation (using XML DOM or XPath instead of RDF to parse the resources). This keeps things open and decoupled.

Efficient representations for a particular use sounds like something that goes in implementation and usage guidance, not a standard. So I think oslc:representation might be a good thing to continue to avoid.

[oslc-bot]

@jamsden: oslc:representation has been added back to the ResourceShapes, and the meaning of LocalResource has been clarified.

[oslc-bot]

@jamsden: Regarding the update to section 2.3 Anti-patterns, changing "Link with inline values of targets" to "Use of Blank Nodes", the end result is the same, but the original anti-patterns was addressing a different problem with blank nodes. If the same value were inlined more than once in the same resource, or if the inlined object also included a URI that was accessed separately, then there could be redundant, possibly inconsistent information in the same file.

[oslc-bot]

@ndjc: The original text had at least two problems. First, if you translate the ‘bad‘ example and the ‘good‘ example to Turtle, you see they are exactly the same - the only difference was in the details of the XML serialization. Second, the recommendation was ruled as poor during TC discussions, since it discouraged the HTML representation of resource A from containing statements about resource B, which contradicts the "Anyone can say anything about anything" http://www.w3.org/TR/2002/WD-rdf-concepts-20020829/#xtocid48014 principle of RDF. Note that there was nothing in the original text about blank nodes - the new anti-pattern is not a rewrite of the original, it is completely unrelated. And yes, that AAA principle indeed implies (as noted in the above reference) that "RDF cannot prevent anyone from making nonsensical or inconsistent assertions, and applications that build upon RDF must find ways to deal with conflicting sources of information".

[oslc-bot]

@berezovskyi: I guess this is not fixed, removing the resolution

[berezovskyi]

Removing the Main spec tag, this issue relates to the Link Guidance OP Note.