add rangeHint and domainHint annotation properties for recommending types in the documentation

[mfhepp]

We often want to use a generic type for range or domain (like Thing or Place) but also point developers to popular specializations (like Restaurant or Vehicle). Instead of logically redundant unions like "Place OR Restaurant" (with Restaurant being a subclass of Place already), we should add two internal "annotation" properties "rangeHint" and "domainHint" that allow explicitly triggering the display of certain schema.org types in the documentation.

... Range: MedicalDevicePurpose Range: Thing

The documentation could then list the formal range (Thing) and popular types for the range (e.g. MedicalDevicePurpose)

This requires just ten lines in the RDFa and tweaking the Python code and Jinja templates that generate the documentation.

Martin

[danbri]

I arrived at a parallel design in github comments yesterday, pretty much while same thing emerged on public-vocabs, see comments in: https://github.com/schemaorg/schemaorg/issues/233

It would probably benefit us to clarify rangeIncludes and domainIncludes first, though...

[elf-pavlik]

I suggested over mailing list to consider instead acknowledging range/domainIncludes as such informal hints. Then instead of even more informal hints, add something something more formal eg owl:unionOf directed at smaller audience of people who build validators or extend schema.org in their vocabularies

• https://lists.w3.org/Archives/Public/public-vocabs/2015Jan/0084.html
• https://lists.w3.org/Archives/Public/public-vocabs/2015Jan/0089.html

Also @gkellogg posted some interesting feedback on this topic

• https://lists.w3.org/Archives/Public/public-vocabs/2015Jan/0101.html

[danbri]

/cc @RichardWallis

[danbri]

I think there is a discussion to be had here, and I'm moving this to suggestions-questions-brainstorming issue tracker as I don't see anything immediately actionable.

Schema.org's domainIncludes and rangeIncludes give us a certain amount of wiggleroom, but we may also want to stand back and look at the 9+ years of consensus building and declare certain domain/ranges as being more "solid". I wouldn't want to add rangeHint and domainHint without looking at it in context of those sorts of consideration. /cc @rvguha

[RichardWallis]

See issue #7 for the context of the move from the main Schema.org issue tracker to this repository.