Re: [oslc-core] Making it easier to write (and read) domain specs (topic for next meeting?)

[John Arwe <johnarwe@us.ibm.com>]

> Range in the tables is not rdfs:range.  

True

I think in the original Martin was confusing other
discussions we had about whether or not the table range constraints Should
be captured in the RDFS for the vocabulary. 


> ...  The meaning of Range is the 
> meaning that you are proposing for "Expected Range".  So
a new 
> column is not necessary. 

If that were true, then there would
be zero need for the existing spec-writing best practice (IIRC in Core
App C) of saying in the description column that the target is "likely"
to be of type A (or at least one of types A, B, ...).

I spent a boat-load of time on this issue 2? 3? years ago in the OSLC Core WG, opened a laundry list of issues because the relationship between the table columns defined in Core and the resource shapes concept in Core Appendix A conflicted, drafted resolutions, and (after discussion) revised the existing text.  In the course of those discussions several things were made clear:

- Sometimes the spec really does intend to say "this type, at least" ... which at one time was common practice, and over time became less common as people debated to what degree that affects implementations' ability to evolve and the open world assumption of RDF.

- Most times the spec intends to say "any" (open world), but implementations (especially clients) should *expect* (be coded to tolerate and exploit if present) a type from the following list ... and the list is very often exactly one element long.

- In NO case are the tables expected to cover all the cases needed by R/W web resources.  The trivial example being that Create and Update usually have very different constraints.  They're basically written for the Update (HTTP PUT semantic) case.

- The tables are expressing constraints agreed on *in the context of currently in-scope scenarios*, in the context of a particular term's use with a particular type.  At one time, apparently the consensus was that in some way the tables "defined" the vocabulary (the two were in a sense inseparable), and as people gained experience with evolving specs to incorporate new scenarios that required different constraints the consensus thinking on the boundary between spec and vocabulary shifted to make them more independent.  Overly constraining the vocabulary term definition artificially forces new terms to be invented, limiting re-use and making the overall system harder to understand (because it's more complex by some metrics).  Certainly I see lots of "new to RDF/OSLC" people reading the tables as if they were typical OO class definitions (where property names are implicitly scoped by the class name, instead of being separately defined and composable).

The need to tell clients of a given spec what to "expect" seems like it would be enduring.  It even seems aligned with Martin's desire to change the style.

The 2119 style is I think what you get when you write specs where the primary consumers are implementers (which usually means *server* implementers), and where some form of formal compliance is at stake.  Personally, I like that style a bit less than I used to *because* it tends to make them largely unreadable by other audiences; I'm thinking nowadays that we almost need two documents for each, one focused on clients and one on servers ... Martin's suggested style being the client-focused one, and its relative paucity of normative requirements might be useful in such a partitioning.  Basically let the WG authors worry about mating the two up, keep all normative requirements for servers in the server-audience spec, and vice versa.  As the skill entry point for app programming continues to be lowered, that seems like a pretty natural evolution; "back in the day" IETF and W3C et al. were only about techies, but they've been so successful that I see a need for the approach to evolve as well.

Best Regards, John

Voice US 845-435-9470  BluePages
Cloud and Smarter Infrastructure OSLC Lead