Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

JSON-LD berücksichtigt ? #10

Closed
akuckartz opened this issue Apr 18, 2013 · 38 comments
Closed

JSON-LD berücksichtigt ? #10

akuckartz opened this issue Apr 18, 2013 · 38 comments
Assignees
Labels
Milestone

Comments

@akuckartz
Copy link
Contributor

Eher eine Frage als ein Issue:

Ist JSON-LD in irgend einer Weise berücksichtigt ?

@marians
Copy link
Contributor

marians commented Apr 18, 2013

Nein, bislang nicht. Grundsätzlich werden Aspekte von Linked Open Data eher als Thema jenseits von Version 1.0 behandelt, da dies inhaltliche Themen sind, die von den Systemen und ihrer Nutzung her aktuell nicht abgedeckt werden. Sprich: Die Daten liegen so nicht vor.

@akuckartz
Copy link
Contributor Author

Ok, hatte ich vermutet (bzw. befürchtet, was das Nicht-Vorliegen der Daten betrifft).

@marians
Copy link
Contributor

marians commented Apr 18, 2013

Das ist ein (komplexes) Thema für die Roadmap bzw. durchaus auch für Anwendungen außerhalb der offiziellen Systeme der Stadt.

Ich könnte mir vorstellen, dass beispielsweise Offenes Köln eines Tages so etwas wie eine Tagging- bzw. eine Taxonomie-Funktion bietet. Damit könnten Nutzer bestimmte Dokumente mit Tags versehen. Diese Tags wiederum könnten im Sinne von Linked-Open-Data mehr als nur ein Stichwort, beispielsweise eine URL auf Wikipedia sein.

Wenn Verwaltungen aber längerfristig einen Sinn darin sehen, den zusätzlichen Aufwand zu betreiben, könnte man auch direkt "an der Quelle" mit derartigen Kategorien arbeiten. Beispielsweise alles, was mit Planfeststellungsverfahren zu tun hat, mit http://de.wikipedia.org/wiki/Planfeststellung verknüpfen. Etc.

@akuckartz
Copy link
Contributor Author

Ich gehöre nebenbei zu dem Apache Stanbol Team (http://stanbol.apache.org). Auch deshalb das Interesse.

@lanthaler
Copy link

Hallo,

bin gerade zufällig auf dieses Projekt gestoßen da JSON-LD gennant wurde. Ich bin einer der Autoren von JSON-LD. Ich finde es würde durchaus Sinn machen sich bereits jetzt mit den Grundzügen von Linked Data zu beschäftigen. Vor allem die verschiedenen Identifier sollten URLs sein. JSON-LD erlaubt die schrittweise Einführung von Linked Data. Traditionelles JSON kann ohne Probleme schrittweise zu Linked Data verwandelt warden.

Zögert bitte nicht mich direkt zu kontaktieren falls irgendwelche Fragen bez. JSON-LD auftreten sollten.

@akuckartz
Copy link
Contributor Author

@lanthaler +1 :-)

@akuckartz
Copy link
Contributor Author

Ich habe mir das etwas genauer angesehen. Wir können relativ einfach mit "@context" und "@type" beginnen. "@id" ist wohl schwieriger.

@akuckartz
Copy link
Contributor Author

Auch "@id" kann jetzt schon verwendet werden :-)

Denn dafür müssen keine IRIs verwendet werden. Vorläufig reichen auch blank node identifier:
http://www.w3.org/TR/2013/WD-json-ld-20130411/#identifying-blank-nodes

Damit spricht nach meiner Kenntnis kein technischer Grund mehr dagegen JSON-LD bereits in der ersten OParl-Version zu unterstützen. Wenn kein Widerspruch kommt, dann modifiziere ich die JSON Beispiele entsprechend.

@marians
Copy link
Contributor

marians commented Apr 22, 2013

Hier ist mein Widerspruch.

Ich habe beim ersten OParl-Workshop und auch hier schon gesagt, dass Linked Open Data (LOD) kein Thema für die Version 1.0, auf die wir gerade hin arbeiten und zum 30. Juni fertig haben wollen, ist.

Bislang sehe ich auch keinen Sinn darin, JSON-LD einfach als Notation einzusetzen, ohne LOD zu unterstützen. Es verkompliziert aber sowohl den Konzeptionsprozess als auch das Ausgabeformat.

Wir haben für Version 1.0 eine Menge Fragen zu beantworten. Diese hier gehört für mich nicht dazu.

@akuckartz
Copy link
Contributor Author

@marians Eine Verkomplizierung des Ausgabeformats gibt es, sie ist aber geringfügig. Der Konzeptionsprozess wird nach meiner Einschätzung sogar vereinfacht, da ein Teil der Zusammenhänge klarer wird und auch Stellen deutlicher werden die bisher nicht spezifiziert sind (und möglicherweise spezifiziert werden können).

@akuckartz
Copy link
Contributor Author

@marians Zu der (wichtigen und berechtigten) Frage nach dem warum: Dadurch können RIS bereits mit Version 1.0 LOD anbieten, ohne dies jedoch zu müssen.

@akuckartz
Copy link
Contributor Author

Zu Blank Nodes versus URI's (und dem Vorzug letzterer) gibt es sogar ein Comic:
http://milicicvuk.com/blog/wp-content/uploads/2011/07/bnode.png

Zur generellen Problematik:
http://richard.cyganiak.de/blog/2011/03/blank-nodes-considered-harmful/

@akuckartz
Copy link
Contributor Author

Ich habe begonnen Material zu den Themen Linked Open Data und JSON-LD auf dieser Seite zu sammeln:
https://github.com/OParl/specs/wiki/Linked-Open-Data

@lanthaler
Copy link

Hab mir die Wiki Page gerade angesehen und ich denke es gibt da ein kleines Mißverständnis bez. @id:

Hierbei muss insbesondere der Umgang mit @id genauer durchdacht werden. Es kann nicht vorausgesetzt werden, dass jede Körperschaft für alle über OParl ausgelieferten JSON Dokumente bereits jetzt eine IRI angeben kann. Deshalb müssen hier auch Identifikatoren angegeben werden können, die weltweit nicht eindeutig sind, sondern nur innerhalb der Körperschaft für die jeweilige Dokumentart. Dazu können die sogenannte "blank nodes" verwendet werden. Die Notation ist z.B. "_:12345" mit dem unterscheidenden Bestandteil "12345".

In JSON-LD is es nicht notwendig blank nodes einen identifier zuzuweisen - es sei denn man muss ihn von anderen Knoten referenzieren können. Das folgende Dokument enhält z.B. einen Identifier der nicht benötigt wird:

{
    "@id": "_:1000",
    "id": "1000",
    "first_name": "Max",
    "last_name": "Mustermann",
    "academic_title": "Dr.",
    "committees": [
        {
            "@id": "_:STA",
            "id": "STA",
            "start": "2013-01-01"
        }
    ]
}

Es kann daher genausogut nur folgendes geschrieben werden:

{
    "id": "1000",
    "first_name": "Max",
    "last_name": "Mustermann",
    "academic_title": "Dr.",
    "committees": [
        {
            "id": "STA",
            "start": "2013-01-01"
        }
    ]
}

Wenn ich mir allerdings die aktuelle Spezifikation ansehe sehe ich folgendes:

Grundlage für den Zugriff auf die Schnittstelle ist das Hypertext Transfer Protocol (HTTP).

Ich stele mir daher die Frage wie auf die einzelnen Datensätze zugegriffen werden kann wenn sie keine eindeutige URL haben. Das verstößt nicht nur gegen Linked Data Prinzipen sondern (noch mehr) gegen die Grundsätze von REST und der Architektur des WWW im Allgemeinen. Vielleicht kann @marians dazu ja was sagen.

@jehrhardt
Copy link

Das Prinzip einer ordentlichen RESTful API ist, dass man sich ausgehend von einer Root-URL durch die gesamte API navigieren kann. Das funktioniert nur über Links. Mir ist z. B. das hier aufgefallen:

{
  "id": "1",
  "name": "Stadt Köln",
  "regionalschluessel": "053150000000",
  "gnd_url": "http://d-nb.info/gnd/2015732-0",
  "url": "http://www.stadt-koeln.de/",
  "operator_contact": "Tel. +49 221-221-5432, E-Mail: ris-api@stadt-koeln.de",
  "license_url": "http://opendatacommons.org/licenses/odbl/1.0/"
}

Leider muss man bei diesem Format eben viel über das Format wissen um es zu benutzen. Alternativ könnte das Format auch so aussehen:

{
  "id": "1",
  "name": "Stadt Köln",
  "regionalschluessel": "053150000000",
  "operator_contact": "Tel. +49 221-221-5432, E-Mail: ris-api@stadt-koeln.de",
  "_links": {
    "alternate": { "href": "http://www.stadt-koeln.de/" },
    "gnd": { "href": "http://d-nb.info/gnd/2015732-0" },
    "license": { "href": "http://opendatacommons.org/licenses/odbl/1.0/" }
  }
}

Das ist natürlich nur eine Variante das ganze abzubilden, es hat aber den Vorteil, dass man wesentlich leichter mit den Links arbeiten kann.

Schlimmer finde ich sogar dieses Beispiel, wo das Prinzip der Verlinkung vollständig ignoriert wird:

{
  "id": "3271",
  "identifier": "STA/0034/2012",
  "start": "2013-01-04T08:00:00+01:00",
  "end": "2013-01-04T12:00:00+01:00",
  "address": "Rathaus, Raum 136",
  "sequence_number": 1,
  "committees": ["STA"],
  "people": ["1000", "1001"],
  "invitation": "0001/2013",
  "result_minutes": "0002/2013",
  "verbatim_minutes": "0003/2013",
  "attachments": [
    "0004/2013",
    "0005/2013"
  ]
}

Eine Alternative mit ordentlichen Links könnte hingegen so aussehen:

{
  "id": "3271",
  "identifier": "STA/0034/2012",
  "start": "2013-01-04T08:00:00+01:00",
  "end": "2013-01-04T12:00:00+01:00",
  "address": "Rathaus, Raum 136",
  "sequence_number": 1,
  "invitation": "0001/2013",
  "result_minutes": "0002/2013",
  "verbatim_minutes": "0003/2013",
  "_links": {
    "committee": { "href": "http://..." },
    "people": [
      { "href": "http://..." },
      { "href": "http://..." }
    ],
    "attachment": [
      { "href": "http://..." },
      { "href": "http://..." }
    ]
  }
}

Ich hoffe, gerade das letzte Beispiel macht deutlich welchen Vorteil Links haben. Jemand, der die API nutzt, muss eben nicht wissen, wie er aus einer Attachment ID eine URL zum downloaden des Attachments macht. Er muss nicht einmal wissen, welche interne ID ein Attachment hat. Ein Attachment muss nichtmal eine ID haben, denn alles was jemand darüber wissen muss, ist die URL. Dasselbe gilt für alle Entitäten also auch für Personen, Drucksachen usw.

Eine Version 1.0 ohne eine Verlinkung der Entitäten untereinander ist doch ziemlich fragwürdig. Sie würde vom API Nutzer verlangen, dass er viel über die Struktur der Daten und sogar der URLs weiß, weil er sich die URLs selber bauen muss. Generische Clients à la RSS Reader, die mit verschiedenen RIS funktionieren, sind so nicht möglich.

Womöglich müsste man sogar die Struktur der URLs spezifizieren, damit sie einheitlich sind. Links erlauben, dass Hersteller URLs strukturieren, wie sie Lustig sind, weil Nutzer immer den Links folgen, die das RIS rausgibt. Damit spart man sich also auch die Notwendigkeit diese zu spezifizieren.

Die Daten untereinander zu verlinken dürfte für die Hersteller auch kein Problem sein, schließlich arbeiten deren RIS auch heute schon mit untereinander verlinkten HTML Seiten.

@jehrhardt
Copy link

@lanthaler @akuckartz könntet ihr ein Beispiel geben, was sich am aktuellen Entwurf durch JSON-LD ändern würde? Mir ist der Vorteil von JSON-LD noch nicht ganz klar. Zumindest wirkt JSON-LD auf den ersten Blick etwas komplex für das Ziel der Verlinkung von Entitäten untereinander derselben API.

@akuckartz
Copy link
Contributor Author

Ich glaube wir sind hier nach und nach dabei uns Beispielen anzunähern - dann sollte auch der Vorteil klar werden und gleichzeitig die Komplexität verschwinden ;-)

Ich denke, dass wir hier alle einer Meinung sind, dass URLs sinnvoll wären, ich fürchte aber, dass die Aussage

Die Daten untereinander zu verlinken dürfte für die Hersteller auch kein Problem sein, schließlich arbeiten deren RIS auch heute schon mit untereinander verlinkten HTML Seiten.

nicht wirklich für alle RIS zutrifft. So habe ich jedenfalls die Aussage von @marians

Die Daten liegen so nicht vor

ganz oben verstanden.

(Ein abschreckendes Beispiel ist leider das RIS der Stadt Dortmund:
http://www.dortmund.de/de/rathaus_und_buergerservice/lokalpolitik/start_lp/index.html )

@lanthaler Es ist wohl bisher beabsichtigt auf einzelne Datensätze gerade nicht mittels einer eindeutigen URL zuzugreifen, sondern über eine noch festzulegende API, der zur Identifikation ein Identifikationsstring (wie die "1000" oben) irgendwie übergeben wird. (Ich habe auch ein git commit gesehem, mit dem eine ursprünglich vorhandene Erwähnung von "REST" entfernt wurde.) Und ich würde gerne JSON-LD nutzen, um statt dem nicht dereferenzierbaren Identifikationsstring alternativ eine dereferenzierbare URL verwenden zu können.

Meine Überlegung hinter "@id": "_:1000" war, dass dann problemlos je nach RIS alternativ eine dereferenzierbare URL als Wert genau dieses Attributs angegeben werden kann.

Soll besser entweder
"id": "1000"
oder
"@id": "http://...."
verwendet werden (je nachdem, ob das konkrete RIS die zweite Alternative ermöglicht)?

@lanthaler Ich bin für alle Vorschläge und Hinweise dankbar. Sehr gut wären einfache Beispiele die zeigen, was ein nicht-URL-taugliches bzw. URL-taugliches RIS jeweils an JSON-LD liefern würden. Beginnen können wir z.B. mit den von @jehrhardt oben schon kritisch gewürdigten Beispielen für Sitzung und Körperschaft:
https://github.com/OParl/specs/blob/master/examples/json/sitzung.json
bzw.
https://github.com/OParl/specs/blob/master/examples/json/koerperschaft.json

EDIT: Habe nun gesehen, dass mittels "id" : "@id" im @context id und @id in Aliasse verwandelt werden können. Sehr praktisch! Damit sind nahezu keine Änderungen für nicht-URL-taugliche RIS gegenüber den bisherigen JSON Beispielen erforderlich.

@akuckartz
Copy link
Contributor Author

@jehrhardt Weil REST oder nicht-REST hier eine gewichtige Rolle spielt:

Laut

a11678d
wurde

Erarbeitung eines Entwurfs für eine REST-Schnittstelle.

durch

Erarbeitung eines Entwurfs für eine HTTP-basierte Schnittstelle

ersetzt. Im Kommentar dazu steht

Hinweis auf REST-Schnittstelle entfernt (Danke Jan Erhardt)

Ich habe nun den Eindruck, als wäre die Entfernung der REST-Schnittstelle so gar nicht beabsichtigt gewesen...

@jehrhardt
Copy link

Ich denke, das bedarf einer Erklärung.

Ich habe mal ein schönes Beispiel für die Verdrehung der Begriffe gesehen. In dem Projekt wurden ursprünglich Diagramme gemalt in denen SOAP als Protokoll an den Kommunikationsbeziehungen zwischen verschiedenen Services stand. Als man sich entschieden hat auf REST umzuschwenken wurde dann REST an diese Kommunikationsbeziehungen geschrieben. Anders als SOAP ist REST aber kein Protokoll, sondern lediglich ein Architektur Paradigma. Die Aussage, zwei Dienste sprechen per REST miteinander, ist z. B. im Kern falsch.

Das Paradigma REST - etwas vereinfacht - bedeutet, dass man durch korrekte Verwendung des HTTP Protokolls eine Web Service Schnittstelle abbilden kann. Man braucht also gar kein zusätzliches Protokoll wie SOAP, das dann durch HTTP getunnelt wird. Bezogen auf das obige Beispiel hätte also HTTP an den Kommunikationsbeziehungen in dem Diagram stehen müssen. Die Aussage, zwei Dienste sprechen per HTTP miteinander, wäre dann auch die richtige.

Genau darum geht es mir wenn ich den Begriff REST aus der Spezifikation raushalten möchte (oben erwähnter Commit). OParl soll auf HTTP basieren und auf dessen korrekter Verwendung, dass man das auch als REST API bezeichnen kann, ist eher unwichtig und führt im Zweifel zu Verwirrung und zusätzlicher Komplexität beim Verständnis.

Gleichzeitig halte ich es für wichtig, dass wir uns an beim Design der API an die Prinzipien des REST Paradigmas halten, soweit das auf unsere Lesen-API zutrifft, denn dieses Paradigma basiert auf den Grundlagen des Webs und OParl soll eine API für das Web werden.

@jehrhardt
Copy link

@akuckartz @marians dass einige RIS nicht mit verlinkten HTML Seiten arbeiten, heißt natürlich nicht, dass die Daten nicht so vorliegen.

Nehmen wir nochmal das obige Beispiel:

{
  "id": "3271",
  "identifier": "STA/0034/2012",
  "start": "2013-01-04T08:00:00+01:00",
  "end": "2013-01-04T12:00:00+01:00",
  "address": "Rathaus, Raum 136",
  "sequence_number": 1,
  "committees": ["STA"],
  "people": ["1000", "1001"],
  "invitation": "0001/2013",
  "result_minutes": "0002/2013",
  "verbatim_minutes": "0003/2013",
  "attachments": [
    "0004/2013",
    "0005/2013"
  ]
}

Dort gibt zwei Personen und ein Gremium, die referenziert werden. Wie sollte denn ein Nutzer der API ausgehend von diesem Datensatz die Daten zu der Person 1001 bekommen? Es gibt drei Möglichkeiten:

  • Es gibt eine URL, in der die ID enthalten ist und auf die man ein HTTP GET macht um die Daten runterzuladen. Der Hersteller, weil er weiß wie die URL aussehen muss, baut sie zusammen und gibt sie in Form eines Links an den Client. Der Client kann dem Link dann einfach folgen.
  • Es gibt ebenfalls eine URL wie im ersten Fall. Die URL muss der Client aber selber zusammenbauen aus den Angaben auf der Herstellerseite (oder wo auch immer) und der ID.
  • Wir verwenden keine URLs auf die ein GET gemacht wird, sondern überlassen dem Hersteller, wie er das umsetzen mag - ggf. per POST.

Ich persönlich bin für Variante eins, weil sie es dem Nutzer einfach macht und einem Client erlaubt ganz generisch auf die API zuzugreifen. Dadurch werden Clients möglich, die automatisch mit verschiedenen RIS arbeiten können. Variante zwei ermöglicht letzteres leider nicht, weil ein Client für jedes RIS die Struktur der URLs kennen muss.

Variante drei wäre aus meiner Sicht fatal, weil die API damit für Clients endgültig unbenutzbar wird.

@akuckartz
Copy link
Contributor Author

@jehrhardt Danke für die Erklärung der Hintergründe der (Nicht-)/Erwähnung von REST, damit hat sich dieser Teil des Nebels nun zumindest für mich gelichtet. Ich halte es allerdings durchaus für hilfreich, wenn in der Spezifikation explizit dargelegt ist, anhand welcher Paradigmen, Kriterien und Anforderungen diese entwickelt wurde und wird.

Ich ziehe selbstverständlich auch Alternative eins vor. Das bedeutet nicht, dass es nicht ausreichen würde, das unterscheidende Endstück der URL und das Anfangsstück separat anzugeben. Das wird durch JSON-LD mittels "@context" schön unterstützt.

http://d-nb.info/gnd/2015732-0

kann z.B. in

http://d-nb.info/gnd/

und

2015732-0

aufgeteilt werden. Das gilt entsprechend auch für die ganzen vom RIS selbst angebotenen URLs. So sollte z.B.

"invitation": "0001/2013"

prinzipiell unverändert bleiben können. Das "/" müssen wir uns dann aber noch genauer ansehen, "0001-2013" oder "2013/0001" wären möglicherweise besser.

@akuckartz akuckartz reopened this Apr 28, 2013
@lanthaler
Copy link

@lanthaler Es ist wohl bisher beabsichtigt auf einzelne Datensätze
gerade nicht mittels einer eindeutigen URL zuzugreifen, sondern über
eine noch festzulegende API, der zur Identifikation ein
Identifikationsstring (wie die "1000" oben) irgendwie übergeben
wird. (Ich habe auch ein git commit gesehem, mit dem eine
ursprünglich vorhandene Erwähnung von "REST" entfernt wurde.) Und
ich würde gerne JSON-LD nutzen, um statt dem nicht
dereferenzierbaren Identifikationsstring alternativ eine
dereferenzierbare URL verwenden zu können.

HTTP arbeitet mir URLs. Wenn es sich nicht um eine SOAP-ähnlich API werden soll, führt meiner Meinung nach wirklich kein Weg an URLs vorbei. Der einzige Weg denn ich sehe ist wie gesagt ein SOAP-ähnliches Interface, d.h., alle IDs werden per POST an eine URL geschickt das dann die jeweiligen Daten zurückgibt. Ich hoffe wirklich sehr dass das nicht so beabsichtigt ist. Und die Erklärungen von @jehrhardt scheinen dies zum Glück auch zu bestätigen.

EDIT: Habe nun gesehen, dass mittels "id" : "@id" im @context id und
@id in Aliasse verwandelt werden können. Sehr praktisch! Damit sind
nahezu keine Änderungen für nicht-URL-taugliche RIS gegenüber den
bisherigen JSON Beispielen erforderlich.

Genau. Es sind so gut wie keine Änderungen nötig. Die einzigen Änderungen um vom Anfang an mit JSON-LD zu starten wäre als media type application/ld+json zu verwenden und (evt.) eine @context Property einzuführen die dann eben einen JSON-LD context referenzieren würde. Das wär's dann auch schon. Ansonsten kann alles gelassen werden wie es zur Zeit ist. Es ist auch nicht nötig spezielle Container wie "_links" einzuführen.

@lanthaler Ich bin für alle Vorschläge und Hinweise dankbar. Sehr gut
wären einfache Beispiele die zeigen, was ein nicht-URL-taugliches
bzw. URL-taugliches RIS jeweils an JSON-LD liefern würden. Beginnen
können wir z.B. mit den von @jehrhardt oben schon kritisch
gewürdigten Beispielen für Sitzung und Körperschaft:

Dafür gibt es verschiedene Möglichkeiten. Im Endeffekt glaube ich dass die aktuellen JSON Strukturen fast unverändert belassen werden können. In den allermeisten Fällen würde einfach nur eine @context Property dazukommen. Evt. wäre auch sinnvoll einzelne Repräsentationen explizit mit einen Typ (@type in JSON-LD, kann aber umbenannt werden) zu kennzeichnen.

Ich denke die wichtigste Entscheidung die zur Zeit getroffen werden sollte ist wie auf die einzelnen Datensätze zugegriffen werden soll. Es geht hier um eine API also ist das eine zentrale Frage. Das offen zu lassen wäre meiner Meinung nach fatal. Falls die Entscheidung auf GETs fällt ist JSON-LD sicher hervorragend geeignet. Je nachdem ob URLs gewissen Strukturen folgen oder nicht ändert sich natürlich die Serialisierung ein bisschen aber das ist meiner Meinung nach Zweitrangig.

Sobald diese Entscheidung feststeht, kann ich mir gerne alle JSON Dokumente ansehen und aufzeigen wie diese in JSON-LD verwandelt werden können.

@lanthaler
Copy link

OK, nochmal direkt über GitHub da alle Formatierungen verloren gegangen sind:

@lanthaler Es ist wohl bisher beabsichtigt auf einzelne Datensätze
gerade nicht mittels einer eindeutigen URL zuzugreifen, sondern über
eine noch festzulegende API, der zur Identifikation ein
Identifikationsstring (wie die "1000" oben) irgendwie übergeben
wird. (Ich habe auch ein git commit gesehem, mit dem eine
ursprünglich vorhandene Erwähnung von "REST" entfernt wurde.) Und
ich würde gerne JSON-LD nutzen, um statt dem nicht
dereferenzierbaren Identifikationsstring alternativ eine
dereferenzierbare URL verwenden zu können.

HTTP arbeitet mir URLs. Wenn es sich nicht um eine SOAP-ähnlich API werden soll, führt meiner Meinung nach wirklich kein Weg an URLs vorbei. Der einzige Weg denn ich sehe ist wie gesagt ein SOAP-ähnliches Interface, d.h., alle IDs werden per POST an eine URL geschickt das dann die jeweiligen Daten zurückgibt. Ich hoffe wirklich sehr dass das nicht so beabsichtigt ist. Und die Erklärungen von @jehrhardt scheinen dies zum Glück auch zu bestätigen.

EDIT: Habe nun gesehen, dass mittels "id" : "@id" im @context id und
@id in Aliasse verwandelt werden können. Sehr praktisch! Damit sind
nahezu keine Änderungen für nicht-URL-taugliche RIS gegenüber den
bisherigen JSON Beispielen erforderlich.

Genau. Es sind so gut wie keine Änderungen nötig. Die einzigen Änderungen um vom Anfang an mit JSON-LD zu starten wäre als media type application/ld+json zu verwenden und (evt.) eine @context Property einzuführen die dann eben einen JSON-LD context referenzieren würde. Das wär's dann auch schon. Ansonsten kann alles gelassen werden wie es zur Zeit ist. Es ist auch nicht nötig spezielle Container wie "_links" einzuführen.

@lanthaler Ich bin für alle Vorschläge und Hinweise dankbar. Sehr gut
wären einfache Beispiele die zeigen, was ein nicht-URL-taugliches
bzw. URL-taugliches RIS jeweils an JSON-LD liefern würden. Beginnen
können wir z.B. mit den von @jehrhardt oben schon kritisch
gewürdigten Beispielen für Sitzung und Körperschaft:

Dafür gibt es verschiedene Möglichkeiten. Im Endeffekt glaube ich dass die aktuellen JSON Strukturen fast unverändert belassen werden können. In den allermeisten Fällen würde einfach nur eine @context Property dazukommen. Evt. wäre auch sinnvoll einzelne Repräsentationen explizit mit einen Typ (@type in JSON-LD, kann aber umbenannt werden) zu kennzeichnen.

Ich denke die wichtigste Entscheidung die zur Zeit getroffen werden sollte ist wie auf die einzelnen Datensätze zugegriffen werden soll. Es geht hier um eine API also ist das eine zentrale Frage. Das offen zu lassen wäre meiner Meinung nach fatal. Falls die Entscheidung auf GETs fällt ist JSON-LD sicher hervorragend geeignet. Je nachdem ob URLs gewissen Strukturen folgen oder nicht ändert sich natürlich die Serialisierung ein bisschen aber das ist meiner Meinung nach Zweitrangig.

Sobald diese Entscheidung feststeht, kann ich mir gerne alle JSON Dokumente ansehen und aufzeigen wie diese in JSON-LD verwandelt werden können.

@jehrhardt
Copy link

@lanthaler @akuckartz @marians ich habe damit begonnen das JSON Format und wie darin navigiert werden kann zu spezifizieren https://github.com/jehrhardt/specs/blob/hyperlinks/dokument/master/chapter_04.md. Ich werde versuchen zeitnah die drei Punkte URL Templating, Listendokumente und ein Indexdokument hinzuzufügen. Ich hoffe damit wird dann klar, wie soetwas aussehen kann.

@lanthaler
Copy link

Was für das Projekt sicher auch von Interesse sein könnte ware Hydra. Vielleicht solltet ihr euch mal die Demo unter http://www.markus-lanthaler.com/hydra/console/ ansehen und dann in der Beschreibung links einfach auf den Link ganz unten klicken.

Das sollte relative schön zeigen was mit JSON-LD möglich ist. Mit relativ wenig Aufwand könnte OParl so beschrieben werden dass es ohne Änderungen direkt in der Hydra Console navigierbar ist.

@akuckartz
Copy link
Contributor Author

@jehrhardt Jedes Beispiel ist gut, aber diese sind viel komplizierter als das mit JSON-LD möglich ist ;-)

Insbesondere sollten in den JSON Dokumenten keine mime-types für referenzierte Dokumente angegeben werden. Die Auswahl des mime-type sollte der http Content Negotiation zwischen Client und zugegriffener Resource überlassen werden.

@marians
Copy link
Contributor

marians commented Apr 29, 2013

Ihr seid der Zeit voraus. Im Moment stehen Fragen zum Datenmodell im Vordergrund. Ich bitte Euch, http://oparl.de/news/2013/04/24/drei-phasen/ zur Kenntnis zu nehmen. Das bedeutet, dass dieser Thread hier erst ab dem 20. Mai wichtig wird. (Sinn dieser Einteilung ist, dass wir uns auf die jeweils wesentlichen Fragestellungen konzentrieren können. Und davon gibt es beispielsweise in #34 eine erste, die immense Bedeutung für den Umfang des Standards in Version 1.0 hat.)

Da hier aber viel gedeutet wird und schon Mißverständnisse im Raum stehen, möchte ich auf ein paar Punkte eingehen.

HTTP/REST: Es soll selbstverständlich so sein, dass Objekte über eine URL via HTTP abgerufen werden. Und das ganze soll zustandslos funktionieren. Also keine Authentifizierung, keine Sessions. Eine der offenen Fragen ist, wie die verwendeten URLs aussehen werden. Eher http://ris.beispielstadt.de/api/agendaitems?meeting_id=123&agendaitem_label=1.2.3 oder eher http://ris.beispielstadt.de/api/meetings/123/agendaitems/1.2.3.json ? Wie gesagt, es würde reichen, wenn wir das Für und Wider ab dem 20. Mai diskutieren.

Zu meiner Aussage "Die Daten liegen so nicht vor": Damit meinte ich nicht etwa interne Verlinkung. Die RISe arbeiten alle intern wie auch an der Oberfläche mit Verlinkung von einem aufs andere Objekt. Mit der Aussage meinte ich die Verlinkung auf externe Entitäten wie z.B. Parteien oder Personen.

@lanthaler
Copy link

Ihr seid der Zeit voraus. Im Moment stehen Fragen zum Datenmodell im Vordergrund. Ich bitte Euch, http://oparl.de/news/2013/04/24/drei-phasen/ zur Kenntnis zu nehmen. Das bedeutet, dass dieser Thread hier erst ab dem 20. Mai wichtig wird.

Ich finde das die Frage ob einzelne Datensätze mit URLs identifiziert/referenziert werden sehr wohl eine Frage des Datenmodell's ist und das war mein Ziel in diesem Thread herauszufinden. Ich stimme jedoch komplett zu dass es noch verfrüht ist Details der Serialisierung zu diskutieren.

HTTP/REST: Es soll selbstverständlich so sein, dass Objekte über eine URL via HTTP abgerufen werden. Und das ganze soll zustandslos funktionieren. Also keine Authentifizierung, keine Sessions.

Das freut mich zu hören. Dann ist ein sehr wichtiger Punkt ja schon geklärt.

Eine der offenen Fragen ist, wie die verwendeten URLs aussehen werden.

Das ist zweitrangig.

Zu meiner Aussage "Die Daten liegen so nicht vor": Damit meinte ich nicht etwa interne Verlinkung. Die RISe arbeiten alle intern wie auch an der Oberfläche mit Verlinkung von einem aufs andere Objekt. Mit der Aussage meinte ich die Verlinkung auf externe Entitäten wie z.B. Parteien oder Personen.

OK, das kann dann wirklich in einer zukünftigen Version addressiert warden. Ich denke es würde aber durchaus Sinn machen das bereits jetzt im Datenmodell zu berücksichtigen.

@marians
Copy link
Contributor

marians commented Jan 13, 2014

Neun Monate nach der letzten Nachricht in diesem Thread frage ich mich, was der aktuelle Stand von JSON-LD ist. Ich bin inzwischen davon überzeugt, dass die Selbstbeschreibungsfähigkeit, die JSON-LD der API geben würde, ein großer Vorteil ist. Aber die entscheidende Frage ist jetzt: Ist JSON-LD "ready for prime time"?

@lanthaler
Copy link

Ja, JSON-LD is „ready for prime time“ :-) Es ist mittlerweile eine „Proposed Recommendation“ (http://www.w3.org/TR/json-ld/). Die Veröffentlichung als offizielle Recommendation, d.h. als endgültiger Standard, ist nur mehr eine Formalität und sollte schon sehr sehr bald erfolgen. Ich werde diese Issue aktualisieren sobald das geschehen ist.

@lanthaler
Copy link

Die JSON-LD Spezifikationen sind nun offizielle W3C Recommendations, d.h. Standards. Die offizielle „Pressemitteilung“ gibt‘s hier: http://www.w3.org/blog/news/archives/3589

Die zwei Spezifikationen hier:

@akuckartz
Copy link
Contributor Author

Workshop: wie vorgeschlagen wird JSON-LD als Grundlage verwendet. Vorschläge für context etc. werden in OParl aufgenommen.

@marians
Copy link
Contributor

marians commented Feb 3, 2014

Aus meiner Sicht wäre noch zu diskutieren, ob für OParl eine bestimmte Form der Syntax gefordert oder empfohlen werden soll. JSON-LD erlaubt ja eine expandierte (expanded) und eine kompakte (compact) Schreibweise.

Beispiel für die kompakte Schreibweise:

{
  "@context": {
    "name": "http://xmlns.com/foaf/0.1/name",
    "homepage": {
      "@id": "http://xmlns.com/foaf/0.1/homepage",
      "@type": "@id"
    }
  },
  "name": "Manu Sporny",
  "homepage": "http://manu.sporny.org/"
}

Analog dazu die expandierte Schreibweise:

[
  {
    "http://xmlns.com/foaf/0.1/name": [
      { "@value": "Manu Sporny" }
    ],
    "http://xmlns.com/foaf/0.1/homepage": [
      { "@id": "http://manu.sporny.org/" }
    ]
  }
]

Auch wenn es hier so aussieht, als wäre die kompakte länger als die expandierte Schreibweise, wird in der Praxis meist die expandierte Form, wie der Name schon sagt, diejenige mit der größeren Payload und, zumindest aus meiner Sicht, der schlechteren Lesbarkeit sein.

@akuckartz
Copy link
Contributor Author

Aus meiner Sicht wäre es ideal, wenn es keine Anforderungen bezüglich expanded / compact geben muss.

Es gibt Libraries für Javascript, Python, PHP, Ruby und Java. Damit kann bei Bedarf zwischen den Formaten hin- und her konvertiert werden. Siehe http://json-ld.org/

Nur wenn dies für einen Hersteller von Client-Software ungünstig wäre (z.B. weil er die von ihm bevorzugte Sprache nicht bei den Libraries findet), sollte eine Festlegung für die Server-Seite erfolgen.

@lanthaler
Copy link

Ich bin auch der Meinung dass es nicht strikt erfordert werden sollte (MUST) aber ich denke es würde durchaus Sinn machen eine bestimmte Form zu empfehlen (RECOMMENDED) und eventuell einen Kontext direkt auf oparl.de zu hosten so dass dieser nur mehr referenziert werden muss.

Marian's Beispiel würde dann z.B. folgendermaßen aussehen was auch gleich den Vorteil dieses Ansatzes schön illustriert:

{
  "@context": "http://json-ld.org/contexts/person.jsonld",
  "name": "Manu Sporny",
  "homepage": "http://manu.sporny.org/"
}

@akuckartz
Copy link
Contributor Author

@lanthaler Ja, entsprechende context-Dateien werden zentral zugänglich gemacht werden (siehe auch #69 ) - und die SOLLEN dann auch genutzt werden.

@marians
Copy link
Contributor

marians commented Feb 4, 2014

Fein. Also eine Empfehlung, die kompakte Form mit unserem bzw. eigenen context-URLs zu verwenden. Gefällt mir.

@marians
Copy link
Contributor

marians commented Apr 23, 2014

Mit dem Commit 3ed3af1 ist die Anforderung zum externen Kontext ebenfalls in das Dokument eingeflossen. Ich schließe daher das Issue.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Development

No branches or pull requests

4 participants