Implement a mechanism for recording context-specific term definitions (textual at least)

[danbri]

We very often have the following workflow:

• someone suggests a new property + textual definition
• someone else says, "hey what about re-using property such-and-so?"
• they agree to re-use an existing property, perhaps tweaking its definition to mention or permit this new usecase.
• result: the original more contextualized definition gets lost.

Generally re-use is good, but it has meant some of our highly re-used properties have definitions that have tended either towards being very bland ("the of the item"), or else being lists of types ("the of the Event, Order, ScholarlyArticle, Person or MedicalCondition").

We should consider allowing per-type documentation strings to be recorded, and to be reflected into the site. I suggest we only do this if/when we integrate a JSON-LD parser into the site tooling (via rdflib), because the markup would be rather complex in RDFa.

Here's an example:

{
  "@context": "http://schema.org/",
  "@id": "http://schema.org/audience",
  "@type": "rdfs:Property",
  "rdfs:label": "audience",
  "rdfs:comment": "An intended audience, i.e. a group for whom something was created.",
  "rangeIncludes": "Audience",
  "customComment": 
    { 
      "@type": "Role",
      "customComment": "The intended audience of the course.",
      "about": {
        "@id": "http://schema.org/Course"
      }
    }
}

Triples (from json-ld playground parser):

• http://schema.org/audience http://schema.org/customComment _:b0 .
• http://schema.org/audience http://schema.org/rangeIncludes "Audience" .
• http://schema.org/audience http://www.w3.org/1999/02/22-rdf-syntax-ns#type
• http://www.w3.org/2000/01/rdf-schema#Property .
• http://schema.org/audience http://www.w3.org/2000/01/rdf-schema#comment "An intended audience, i.e. a group for whom something was created." .
• http://schema.org/audience http://www.w3.org/2000/01/rdf-schema#label "audience" .
• _:b0 http://schema.org/about http://schema.org/Course .
• _:b0 http://schema.org/customComment "The intended audience of the course." .
• _:b0 http://www.w3.org/1999/02/22-rdf-syntax-ns#type http://schema.org/Role .

Of course this would only be worth doing if we integrated the text back into our site somewhere.

Related issues: JSON-LD support; multi-lingual labels.

[danbri]

This only really makes sense after we get the ability to write schemas in JSON-LD. see also schemaorg/schemaorg#178 (do we have an issue for actually using rdflib to permit json-ld schemas? can't find one...).

[danbri]

I don't like the Role-based design sketched here, but this is a common situation. Parties using schema.org are naturally inclined towards re-use, but the more they re-use rather than create new terms, the less they're provided with a surface for documenting and defining. There is some connection to the notion of shapes here - see https://github.com/schemaorg/schemaorg/issues/1715

Tagging this for continued discussion in the suggestions-questions-brainstorming repo

[RichardWallis]

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