Herstellerspezifische Namenspräfixe für Eigenschaften, URL-Parameter, Methoden etc. außerhalb des Standards

[marians]

Das Thema wurde beim Workshop gestern (17.4.) schon andiskutiert. Wenn Hersteller Ihre API um Eigenschaften, URL-Parameter etc. erweitern wollen, die nicht im Standard definiert sind, kann es bei zufälliger Benennung zu Überschneidungen bei zukünftigen Weiterentwicklungen des Standards kommen.

Angenommen, der Standard definiert eine Klasse "Person" mit nur einer Eigenschaft "name":

{
    name: "Hans Wurst"
}

Hersteller A möchte zusätzlich das Geburtsdatum der Person mit ausgeben können und nennt die Eigenschaft "date".

{
    name: "Hans Wurst",
    date: "1970-01-01"
}

Nun wird der Standard erweitert und die Klasse "Person" soll ein eine weitere Eigenschaft für das Beitrittsdatum der Person mit dem Namen "date" bekommen. Hierdurch kommt es zu einem Namenskonflikt. Hersteller A muss seine Implementierung anpassen, sonst liefert die Eigenschaft "date" nicht den erwarteten Wert.

Eine mögliche Lösung hierfür sind hersteller-spezifische Namenspräfixe. Nehmen wir an, der Hersteller A hat das Namenspräfix herstellera gewählt, dann wäre, in Anlehnung an MIME Types und HTTP Header folgende Nomenklatur möglich:

{
    name: "Hans Wurst",
    x-herstellera-date: "1970-01-01"
}

Gleiches gilt für URL-Parameter. Beispiel:

/api/people?x-herstellera-date=1970-01-01

Für herstellerspezifische Methoden könnte dieses Prinzip ebenfalls eingesetzt werden. Beispiel:

/api/x-herstellera-supermethode?foo=bar

Dies lässt als Herausforderung übrig, dass die Vergabe der Namenspräfixe zumindest zentral dokumentiert werden sollte. Das können wir leisten.

[akuckartz]

Die Menge der RIS-Hersteller ist ja einigermassen überschaubar. Falls diese bereit sind, solche (kaum wettbewerbsentscheidenden) Neuerungsvorhaben vorher bekannt zu geben und damit zur Diskussion zu stellen, dann erübrigen sich möglicherweise solche herstellerspezifischen Dinge.

[jehrhardt]

Zum einen ist jeder Hersteller frei darin derartige Prefixe zu verwenden oder nicht. Oder anders gesagt, es spricht nichts dagegen, dass Clientseitige Parser fehlertolerant implementiert werden und nicht standardisierte Attribute ignorieren. Meines Wissens nach ist auch die Verwendung von Herstellerprefixen in Browsern nicht spezifiziert, sondern eine Praxis, die sich etabliert hat. Ich sehe daher nicht wirklich ein Problem darin und würde diesen Punkt bewusst offen lassen.

Eine weitere Möglichkeit wäre einen optionalen Bereich zu schaffen, in dem beliebige nicht spezifizierte Eigenschaften Platz finden. Bezogen auf obiges Beispiel:

{
  "name": "Hans Wurst",
  "options": {
    "date": "1970-01-01"
  }
}

[jehrhardt]

Was Prefixe für URL Parameter betrifft, muss ich sagen, dass ich von einer Spezifikation von URLs oder gar URL Parametern abraten würde. Allgemein sind URL Parameter eher schlechter Stil, aber wer aus welchen Gründen darauf setzen will, sollte das tun können. Wie er sie nennt ist seine.

Eine Suche kann bequem über einen Such Link abgewickelt werden:

{
  "_links": {
    "search": {  "href": "http://meinestadt.de/search{?query}", "templated": true }
  }
}

Der Suchlink in dem Beispiel wird über ein URI Template abgebildet. Dabei würde ich allerdings nur die Variablennamen wie in diesem Fall query spezifizieren. Das ganze ist sehr flexibel:

query := "rathaus"

http://meinestadt.de/search{?query}      => http://meinestadt.de/search?query=rathaus
http://meinestadt.de/search?q={query}    => http://meinestadt.de/search?q=rathaus
http://meinestadt.de/search/{query}/     => http://meinestadt.de/search/rathaus/

Damit kann jeder seine URLs gestalten wie es ihm am besten passt.

[akuckartz]

Die Frage sollte auch in Zusammenhang mit einer eventuellen Verwendung von JSON-LD betrachtet werden (um Inkompatibilitäten mit der Zukunft zu vermeiden :-)

Nach meiner aktuellen Einschätzung wäre so etwas unproblematisch:
"herstellera:date": "1970-01-01"

[akuckartz]

URL-Parameter halte ich ebenso wie @jehrhardt nicht für gut. Wenn ich die angegebenen Beispiele richtig interpretiere, dann geht darin tatsächlich "nur" um die Suche nach Objekten.

[marians]

Ich habe für das Thema URL-Parameter ein neues Issue #30 angelegt. Hier soll es eigentlich darum gehen, ob wir im Standard eine Empfehlung abgeben, wie man nicht spezifizierte Dinge benennen kann, um Namenskonflikte möglichst zu vermeiden.

[robbash]

Das Argument für herstellerspezifische Präfixe war, dass namensgleiche Eigenschaften später noch in den Standard aufgenommen werden können, und nicht für Spezielles eines Herstellers vergeben sind.

[akuckartz]

Ich greife mal vor: Das ist mit JSON-LD kein Problem.

Dazu hatte ich oben als willkürliches Beispiel

"herstellera:date": "1970-01-01"

angegeben.

Für

"herstellera:date"

kann dann gegebenenfalls nach erfolgter Standardisierung mittels @context der Name "date" als Alias angegeben werden (wenn nicht ohnehin gleichzeitig das "herstellera:" entfernt wird).

[marians]

Ich versuche es mal mit einem JSON-LD Beispiel. Angenommen, dieses Objekt wäre OParl-konform, weil OParl das Schema http://oparl.de/schema/Foo definiert:

{
    "@context": {
        "Foo": "http://oparl.de/schema/Foo"
    },
    "@id": "http://www.meinris.de/api/12345",
    "@type": "Foo",
    "name": "Name des Objekts"
}

Das Attribut "name" wäre in http://oparl.de/schema/Foo definiert.

Wenn ich JSON-LD richtig verstehe, könnte ein Hersteller oder Betreiber das Objekt beispielsweise so um eigene Attribute erweitern:

{
    "@context": {
        "Foo": "http://oparl.de/schema/Foo",
        "Bar": "http://www.meinris.de/schema/Bar",
    },
    "@id": "http://www.meinris.de/api/12345",
    "@type": ["Foo", "Bar"],
    "name": "Name des Objekts",
    "description": "Beschreibung des Objekts"
}

Das Attribut "description" wäre in http://www.meinris.de/schema/Bar definiert.

Richtig?

Wie vermeidet man Namenskonflikte, wenn OParl irgendwann auf die Idee kommt, das Schema http://oparl.de/schema/Foo um "description" zu erweitern? Im Regelfall weiß OParl nicht mal von der Existenz von http://www.meinris.de/schema/Bar.

[akuckartz]

Bin heute und morgen unterwegs. Eventuell kann @lanthaler das zwischenzeitlich beantworten?

[marians]

Habe noch mal in die JSON-LD Specs geguckt. Sieht aus, als würden für solche Zwecke Namespace-Präfixe genutzt. Also z.B. "Foo:description" und "Bar:description". Sieht für mich gut aus.

[lanthaler]

In der Regel wird jeder "term" im Context zu einer URL gemappt. Da diese jedoch schnell zu sehr großen Contexts führt, gibt es zwei Mechanism um dass effizienter zu gestalten: prefixes und @vocab. Ein Prefix steht für einen Subnamespace. Würde z.B. oparl zu http://oparl.de/schema/ gemappt, wurde die Verwendung von oparl:Foo für die URL http://oparl.de/schema/Foo stehen. In vielen use cases gibt es ein "Hauptvokabular" (für SEO z.B. Schema.org). Hier bietet sich dann die Verwendung von @vocab an das so zu sagen einen globalen Prefix definiert. Alle terms die nicht explizit zu etwas anderes gemappt sind, werden an die @vocab URL angehängt. Hier ein Beispiel das alle Fälle beinhaltet:

{
    "@context": {
        "@vocab": "http://oparl.de/schema/",
        "Bar": "http://www.meinris.de/schema/Bar",
        "herstellerX": "http://herstellerx.de/vocab#"
    },
    "@id": "http://www.meinris.de/api/12345",
    "@type": [ "Foo", "Bar"],
    "name": "Name des Objekts",
    "description": "Beschreibung des Objekts",
    "herstellerX:property": "eine proprietäre Property von Hersteller X"
}

Die absoluten URLs sehen nun so aus:

{
    "@id": "http://www.meinris.de/api/12345",
    "@type": [ "http://oparl.de/schema/Foo", "http://www.meinris.de/schema/Bar"],
    "http://oparl.de/schema/name": "Name des Objekts",
    "http://oparl.de/schema/description": "Beschreibung des Objekts",
    "http://herstellerx.de/vocab/property": "eine proprietäre Property von Hersteller X"
}

Für OParl würde ich die Verwendung von @vocab empfehlen da es den Context so klein als möglich hält. Hersteller können dann entscheiden ob sie einen Prefix einsetzen wollen oder die nötigen terms direkt im Context definieren (was den Vorteil hat das das JSON keine : enthält und daher leichter in, z.B., JavaScript verwendbar ist).

[marians]

Danke für die Info! Wenn es richtig verstehe, ist man aber davor, dass "herstellerX" in verschiedenen Vokabularen vorkommt, nicht sicher. Der Betreiber der API muss ggf. dafür sorgen, das Eindeutigkeit herrscht, indem statt der Kurzform "herstellerX" die URL-Form verwendet wird.

Zur Handlichkeit in JavaScript: URLs als Attribute sind ja auch nicht gerade förderlich, was das betrifft.

[lanthaler]

Danke für die Info! Wenn es richtig verstehe, ist man aber davor, dass "herstellerX" in verschiedenen Vokabularen vorkommt, nicht sicher. Der Betreiber der API muss ggf. dafür sorgen, das Eindeutigkeit herrscht, indem statt der Kurzform "herstellerX" die URL-Form verwendet wird.

herstellerX ist ein Prefix der dann in herstellerX:property genutzt wird. Es stimmt, falls zwei Hersteller den gleichen Prefix verwenden kommt es _theoretisch_ zu Problemen. In der Praxis ist das kein Problem da der API Publisher ja weiß welche Namespaces er verwendet und damit Kollisionen vermeiden kann-der Prefix kann ja beliebig gewählt werden.

Zur Handlichkeit in JavaScript: URLs als Attribute sind ja auch nicht gerade förderlich, was das betrifft.

Ist mit "Attribute" der member name oder der member value eines JSON objects gemeint? JSON-LD erlaubt es URLs im body (also außerhalb von @context) weitgehendst zu vermeiden. Somit sollte das kein Problem sein.

Das einfachste wäre wahrscheinlich sich ein paar konkrete Beispiele anzusehen. Abstrakte Diskussionen sind immer schwierig...

[akuckartz]

Workshop: SHOULD URL-Präfix soll herstellerspezifisch sein.

[akuckartz]

Ich habe in Abschnitt 8000 ein ganz kurzes Beispiel ergänzt.

Hier gibt es anscheinend nichts mehr zu tun. Deshalb wird dieses Issue geschlossen.