Zum Hauptinhalt springen

Links

links speichert einen Hauptlink und optionale alternative Links, jeweils eine URL mit einer optionalen, lesbaren Bezeichnung. Verwenden Sie ihn für Webseiten, Dokumentation, Support-Adressen oder Telefonlinks, die zu einem Datensatz gehören. Gewöhnliche text-Attribute bleiben unverändert: Ein Textwert, der zufällig wie eine URL aussieht, wird nie umgewandelt.

Wert​

{
"primary": { "url": "https://example.com/docs", "label": "Documentation" },
"alternatives": [
{ "url": "mailto:support@example.com", "label": "Support" },
{ "url": "https://status.example.com" }
]
}
ElementRegeln
primaryPflicht, sobald der Wert vorhanden ist. Ein Linkobjekt.
alternativesBeim Schreiben optional, beim Lesen immer ein Array. Geordnet; höchstens 10 Einträge.
urlPflicht je Link. Getrimmt, 1 bis 2048 Zeichen, eine absolute URL mit http, https, mailto oder tel. Web-URLs brauchen einen Host.
labelOptional je Link. Getrimmt, höchstens 200 Zeichen; leere Bezeichnungen entfallen.

Dieselbe URL darf über Hauptlink und Alternativen hinweg nur einmal vorkommen. Beim Speichern oder Anzeigen eines Links wird sein Ziel nie kontaktiert: keine Vorschauen, kein Crawling, keine Metadaten.

Ein mitgesendeter Wert ersetzt den gespeicherten Wert vollständig. Um eine Alternative zum Hauptlink zu machen, senden Sie die Struktur mit diesem Eintrag als primary und dem bisherigen Hauptlink in alternatives; die API speichert die empfangene Struktur.

Leere Werte​

Ein Wert ohne Hauptlink und ohne Alternativen, etwa {} oder {"alternatives": []}, ist leer. Er leert das Attribut genau wie null: Ein optionales Attribut wird entfernt, ein Pflichtattribut liefert 422 required-field. Alternativen ohne Hauptlink liefern 422 links-primary-required.

Validierungsfehler​

FehlertypUrsache
type-mismatchDer Wert, ein Link oder alternatives hat die falsche Form; der Pointer benennt das Element, zum Beispiel #/data/website/alternatives/1.
unknown-fieldEin anderes Element als primary, alternatives, url oder label.
required-fieldEin Link ohne url.
links-unsafe-linkEine URL mit einem anderen Schema als http, https, mailto oder tel.
invalid-formatEine URL, die nicht geparst werden kann, keinen Host hat oder Leerraum oder Steuerzeichen enthält.
string-too-longEine url oder ein label überschreitet die Längengrenze.
duplicate-itemsDieselbe URL kommt zweimal vor; der Pointer benennt die wiederholte Alternative.
too-many-itemsMehr als 10 Alternativen.
links-primary-requiredAlternativen wurden ohne Hauptlink gesendet.

Anzeige​

Anzeigevorlagen und kompakte Listenzellen zeigen die Bezeichnung des Hauptlinks oder seine URL, wenn er keine Bezeichnung hat. Die Tourfold-Web-App stellt jeden Link als seine Bezeichnung mit der URL als Tooltip dar; Weblinks öffnen sich in einem neuen Tab mit rel="noopener noreferrer", Mail- und Telefonlinks werden an das Gerät übergeben, und eine URL mit einem anderen Schema wird als reiner Text angezeigt. Konsumenten, die gespeicherte Links darstellen, sollten dieselbe Schema-Regel anwenden.

Definition​

{
"slug": "website",
"type": "links",
"name": {"en": "Website", "de": "Webseite"},
"config": {"is_required": false}
}
KonfigurationVerhalten
is_requiredEin Hauptlink muss vorhanden sein.
defaultNicht verfügbar.
is_uniqueNicht unterstützt; liefert 422 unique-unsupported-type.

Abfragefähigkeiten​

OberflächeFähigkeit
REST filter_operatorscontains und is_null (is_null nur bei optionalen Attributen)
REST is_sortablefalse
GraphQL-AusgabeRecordLinks { primary: RecordLink!, alternatives: [RecordLink!]! } mit RecordLink { url: String!, label: String }
GraphQL-FilterLinksOperators mit _contains und _is_null
GraphQL order_byNicht verfügbar
SucheBezeichnungen und URLs aller Links werden indexiert; Elementnamen nicht

contains vergleicht die Bezeichnungen und URLs aller Links ohne Beachtung der Groß-/Kleinschreibung. Gleichheits-, Präfix- und Suffixoperatoren liefern 422 filter-operator-not-applicable, eine Sortierung liefert 422 unsupported-sort-field.

Integrationsoberflächen​

Webhook-Nutzdaten, MCP-Datensatzwerkzeuge, Workflow-Datensatzoperationen und Fahrzeugdefinitionen übertragen dasselbe Objekt innerhalb von data, genau wie REST es zurückgibt, wobei alternatives immer vorhanden ist.