Spec Terms

[csarven]

Spec Terms provides classes and properties that can be used to describe any significant unit of information in technical reports.

Influenced by a number of works encompassing W3C processes, specification authoring and publishing, quality assurance, e.g.:

• https://www.w3.org/Consortium/Process/
• https://www.w3.org/TR/spec-variability/
• https://www.w3.org/TR/qaframe-spec/
• https://www.w3.org/TR/test-metadata/
• https://www.w3.org/TR/EARL10-Schema/

It is currently used by Solid Technical Reports, conformance test suite coverage documents, and applications e.g.:

• https://solidproject.org/TR/protocol (see https://solidproject.org/ED/protocol for most current use.)
• https://solidproject.org/TR/wac
• https://solidproject.org/TR/notifications-protocol
• https://solid-contrib.github.io/specification-tests/coverage
• https://dokie.li/

The work here fits within the scope of https://github.com/solid/process/blob/main/test-suite-panel-charter.md , W3C QA activities, and the practice (the art?) of writing technical reports.

The work here is far from "complete" and there is much to look ahead. Consumers of the vocabulary should note that it currently has the status of "testing". The work here is mature enough to open up further, i.e., merge to main branch and deploy changes regularly under the designated namespace, and gather more implementation experience.

This is also a call to gather feedback to improve the vocabulary design; to encourage its use in publication of technical reports; to encourage the consumption of machine-readable technical reports by exciting applications.

[csarven]

I agree it should be consistent or clarified as much as possible. Various things are under specified and they'll need to be reviewed.

[csarven]

@karlcow , hi! :)

[csarven]

@edwardsph , I've added owl:ObjectProperty to some properties in https://github.com/solid/vocab/pull/84/commits/cd81f14fa2642d844ac972c171e0f0a67712767e . If things break, it is your fault.

[matthieubosquet]

@kjetilk’s comment makes me think: I’m not sure why we would use a different casing convention and - for those terms.

Couldn’t we simply keep all terms camel case (classes/concepts/named individuals upper and properties lower)?

[csarven]

I won't bother diving into the template or readability that I applied or try to convince everyone here. Open to whatever convention but I'll just say that simple patterns/consistency is not necessarily ideal in the end.

Having said that, I'm okay with convention camelCase and TitleCase. The property/class name is generally intended to be derived from the natural language label.

I'll propose example changes here and if we can get a few +1/-1, I can update the PR:

• MUST-NOT -> MUSTNOT -- dropping - and keeping this all uppercase because of RFC 8173. Similar terms where case sensitivity is meaningful will be retained and not changed for the purpose of the vocab.
• strongly-encouraged -> StronglyEncouraged -- dropping - and going with TitleCase.
• "Producer of content" from label -> ProducerOfContent concept -- that's what's used at the moment, but ProducerContent seems okay too - does anyone have opinions on this?

If there are other ones issues or preferences, let's get them in. Thanks.

[matthieubosquet]

I'll propose example changes here and if we can get a few +1/-1, I can update the PR:

• MUST-NOT -> MUSTNOT -- dropping - and keeping this all uppercase because of RFC 8173. Similar terms where case sensitivity is meaningful will be retained and not changed for the purpose of the vocab.
• strongly-encouraged -> StronglyEncouraged -- dropping - and going with TitleCase.
• "Producer of content" from label -> ProducerOfContent concept -- that's what's used at the moment, but ProducerContent seems okay too - does anyone have opinions on this?

+1 on all of those with a preference for full forms such as ProducerOfContent.