From pohl at hbz-nrw.de  Wed Mar  6 15:43:27 2019
From: pohl at hbz-nrw.de (Adrian Pohl)
Date: Wed, 6 Mar 2019 15:43:27 +0100
Subject: [dini-ag-kim-oer] =?utf-8?q?Spezifikation_der_Visitenkarte_f?=
 =?utf-8?q?=C3=BCr_OER-Dienste?=
Message-ID: <6e90314a-2226-3712-2ac0-4d7df2f720db@hbz-nrw.de>

Liebe Leute,

wir hatten uns ja in kleiner Runde am 12., 19, und 26. Februar 
getroffen, um die Spezifikation einer Visitenkarte f?r OER-Dienste im 
Web zu finalisieren.

Wir sind ziemlich weit gekommen. Um den aktuellen Stand festzuhalten, 
habe ich habe gestern und heute auf GitHub einige Dinge aktualisiert und 
erg?nzt:

1. Dokumentation

Ich habe mit GitHub Pages den ersten Wurf einer [Dokumentation] 
angelegt. Es handelt sich um die Beispielvisitenkarte, die mit 
hypothes.is annotiert ist. Bei einem Klick auf ein gelb markiertes Feld 
geht die Dokumentation des Feldes auf.

Meines Erachtens ist das eine bessere Art der Dokumentation als so eine 
[Liste], wie wir sie zun?chst angelegt hatten. Ich w?rde auch ungern 
parallel zum Schema und dieser Dokumentation noch eine solche 
Felderliste pflegen. Was meint ihr?

Der aktuelle Stand ist nat?rlich noch nicht gut genug. Wenn ich etwas 
anpassen oder erg?nzen soll, gebt mir bescheid, am besten mit einem 
Kommentar an der jeweiligen hypothes.is-Annotation. (Daf?r m?sst ihr ein 
hypothes.is-Konto anlegen.) Ich habe bereits selbst ein paar Kommentare 
erg?nzt, wo ich selbst noch Diskussionsbedarf sehe (about, serviceType, 
schemaVersion, sameAs).

2. JSON Schema

Das JSON [Schema] habe ich entsprechend unserer Ergebnisse aktualisiert. 
Was noch fehlt ist die Angabe der Pflichtfelder.

3. Beispiel-Visitenkarte

Das [Beispiel] ist nun (beinahe) up-to-date.

Die Angabe der Version mit `schemaVersion` ist noch nicht korrekt, da 
wir hier auf eine Version des Schemas verlinken wollen und somit eine 
URL als Wert gefordert ist. Dementsprechend gibt es auch eine Meldung 
bei der Validierung des Beispiels gegen das Schema. (Validieren l?sst 
sich das z.B. auf der Kommandozeile mit ajv: $ ajv -s service-card.json 
-d service-card-example.json )


Zum weiteren Vorgehen: Mein Vorschlag ist, die [Dokumentation] als 
kanonische Spezifikation der Visitienkarte auszubauen. So h?tten wir 
alle wesentlichen Teile der Spezifikation (Schema, Dokumentation, 
Beispiel) in einem git-Repo. Es k?nnte sogar sinnvoll, f?r diese 
Spezifikation ein ganz eigenes git-Repo anzulegen...

Ciao
Adrian

[Dokumentation] 
https://dini-ag-kim.github.io/oer-metadata-schemas/service-card.html

[Liste] 
https://docs.google.com/document/d/15maQjLpDdrhQArKvAcmz11LpdB77L9JAC_9JOhV7l98/edit#heading=h.ku9tbhhbdgli

[Schema] 
https://github.com/dini-ag-kim/oer-metadata-schemas/blob/master/service-card.json

[Beispiel] 
https://github.com/dini-ag-kim/oer-metadata-schemas/blob/master/service-card-example.json