Inhoud vd specificatie documenten

[GeertThijs]

Nu ik een zgn voorbeeld-inleiding voor de vocs/ap’s aan het schrijven ben (voor Persoon) zit ik met volgende vragen over de inhoud vd spec documenten:

• De huidige voc documenten zijn erg minimaal. Dat is omdat ze soms niet meer dan een vertaling van bestaande termen inhouden (Dienst), iets dat zelfs enkel in de RDF te zien is. En als ze al meer termen toevoegen aan bestaande vocabularia (een beetje bij Organisatie, relatief veel bij Persoon en Adres) staat in de vocspec enkel de definitie vd termen (zelfs de usagenote ontbreekt, @Laurens: kan jij ervoor zorgen dat die toch zichtbaar wordt?). De context waarbinnen de nieuwe termen zijn toegevoegd ontbreekt eveneens, maar daarvoor dienden dus die fameuze inleidingen.
• Vraag is nu: wat zetten we in die inleiding (of misschien beter: beschrijving)? Het is moeilijk om het enkel te hebben over de toegevoegde termen, zeker als er helemaal geen zijn (Dienst) of slechts enkele (Organisatie). Zelfs bij Persoon en Adres stelt zich het probleem. Bvb bij Persoon komt de entiteit Persoon van ISA-CPV inclusief een aantal eigenschappen (maar niet allemaal), bvb naam, geslacht ed.
• Mogelijke opties:

1. Toch een volledige beschrijving geven vh vocabularium, zelfs als het amper nieuwe of zelfs geen termen bevat. Kwestie van een samenhangend verhaal te hebben en ook: een verhaal in het Nederlands aangezien elk vocabularium verwijst naar bestaande vocabularia. Vereist ook een figuur met het datamodel maar dan zonder de restricties vh applicatieprofiel.
2. Een gedeeltelijke beschrijving vh vocabularium, maw enkel die termen die het vocabularium aan bestaande vocabularia toevoegt. Kan soms raar zijn: bvb we voegden contactinfo en gebruikteVoornaam toe aan de bestaande eigenschappen van ISA-Persoon en zouden dus moeten volstaan met een beschrijving van deze eigenschappen (die eigenlijk ook bij de definities zal gevonden worden).
3. Geen algemene beschrijving vh vocabularium. Sowieso zegt de beschrijving meer over hoe de termen geïnterpreteerd (gebruikt?) moeten worden waardoor ze eerder thuishoort in het applicatieprofiel (of de applicatieprofielen).
4. Een apart document met de beschrijving. Zowel vocabularium als applicatieprofielen kunnen daarnaar verwijzen. Dat document is een beschrijving van het domeinmodel vh betrokken thema en houdt naast de beschrijving dus ook een datamodel in evenals verwijzingen naar andere modellen, literatuur etc.

• Optie 1 is problematisch omdat ze als er veel termen herbruikt worden niet meer dan een vertaling kan zijn van de beschrijving bij de vocabularia waarnaar ze verwijst. Tegelijk suggereert ze ten onrechte dat een compleet nieuw vocabularium wordt gepresenteerd. Vooral als daarna geen klassen of eigenschappen gedefinieerd worden getoond zoals bij Dienst. Waardoor wellicht moet worden afgestapt vh feit dat we in een vocabularium document enkel nieuwe termen laten zien.
• Bij optie 2 is het probleem dat de samenhang ontbreekt als enkel nieuwe termen worden beschreven. Het wordt aan de lezer overgelaten om deze samenhang te zoeken door de vocabularia waarnaar gerefereerd wordt erbij te nemen.
• Negatief bij optie 3 is dan weer dat het probleem wordt doorgegeven naar een applicatieprofiel waardoor wie enkel het vocabularium document bekijkt in de kou blijft. Bovendien is een context-neutrale beschrijving nodig vh thema of domein, terwijl we in het applicatieprofiel een context opvoeren (de applicatie) en het bijkomend al direct moeten hebben over de restricties die die context meebrengt.
• Optie 4 is de minst problematische. Men heeft weliswaar een derde document nodig om het verhaal achter het vocabularium en het profiel te snappen, maar dat document beperkt zich tot dat verhaal en de vocabularium- en applicatieprofiel-documenten focussen zich op hun eigen boodschap: nl resp wat wordt toegevoegd aan bestaande vocabularia en welke restricties op het vocabulariium en bestaande vocabularia worden geplaatst ihkv een specifieke toepassing (of in ruimere zin hoe de termen uit deze vocabularia in praktijk moeten worden gebruikt).

In afwachting van jullie commentaar ga ik alvast oor de laatste optie.

[GeertThijs]

Voorbeeld van optie 3 (eigenlijk meer een variant) is CPSV-AP: zij hebben geen voc-specificatiedocument voor de uitbreiding die CPSV-AP doet op CPSV, zij publiceren gewoon een CPSVAP-RDF (met kardinaliteiten in de comment!?) en het ap-specificatiedocument licht zowel de nieuwe termen als het profiel toe. Problematisch toch ook wel: alles loopt door elkaar: wanneer slaat de beschrijving op de applicatie en wanneer niet? En optie 4 wordt toegepast bij Web Annotation: datamodel https://www.w3.org/TR/annotation-model/ en vocabularium https://www.w3.org/TR/annotation-vocab/ zijn aparte documenten.

[jensscheerlinck]

Voor mij is de HTML versie van het vocabularium een document dat in de eerste plaats bruikbaar moet zijn door de gebruikers (mensen). De "échte" definitie van het vocabularium zit vervat in het Turtle bestand.

Een apart document, zoals het Web Annotation datamodel is een mogelijkheid, maar dan moet het Voc een ondersteunende rol hebben en niet zo prominent aanwezig zijn (bv. de eerste pagina weer mensen naartoe surfen is dan het data model document). Ook praktisch gezien lijkt dit een hoop extra werk, plus dat voor wat betreft ISA Persoon of CPSV-AP wij (AIV-OSLO) misschien niet het best geplaatst zijn om dit te schrijven.

Een mogelijkheid zou zijn om in een apart hoofdstuk, op het einde, de klassen en eigenschappen op te nemen die werden hergebruikt uit andere vocabularia, samen met het label en eventuele definitie in het Nederlands.

Een voorbeeld hiervan is: https://www.w3.org/TR/annotation-vocab/ (hoofdstuk 3)

Het domein en bereik van de hergebruikte termen zou rechtstreeks kunnen opgehaald worden uit de desbetreffende namespaces (automatisch, via een script).

Tot slot, in plaats van een volledig domein model weer te geven zoals bij de APs (waar impliciet de klassen en attributen al in een bepaald stramien gegoten worden), kan zoals bij de Web Annotation Ontology gekozen worden om kleine diagrammen op te nemen bij de klassen en eigenschappen zelf.