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" }
]
}
| Element | Regeln |
|---|---|
primary | Pflicht, sobald der Wert vorhanden ist. Ein Linkobjekt. |
alternatives | Beim Schreiben optional, beim Lesen immer ein Array. Geordnet; höchstens 10 Einträge. |
url | Pflicht je Link. Getrimmt, 1 bis 2048 Zeichen, eine absolute URL mit http, https, mailto oder tel. Web-URLs brauchen einen Host. |
label | Optional 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
| Fehlertyp | Ursache |
|---|---|
type-mismatch | Der Wert, ein Link oder alternatives hat die falsche Form; der Pointer benennt das Element, zum Beispiel #/data/website/alternatives/1. |
unknown-field | Ein anderes Element als primary, alternatives, url oder label. |
required-field | Ein Link ohne url. |
links-unsafe-link | Eine URL mit einem anderen Schema als http, https, mailto oder tel. |
invalid-format | Eine URL, die nicht geparst werden kann, keinen Host hat oder Leerraum oder Steuerzeichen enthält. |
string-too-long | Eine url oder ein label überschreitet die Längengrenze. |
duplicate-items | Dieselbe URL kommt zweimal vor; der Pointer benennt die wiederholte Alternative. |
too-many-items | Mehr als 10 Alternativen. |
links-primary-required | Alternativen 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}
}
| Konfiguration | Verhalten |
|---|---|
is_required | Ein Hauptlink muss vorhanden sein. |
default | Nicht verfügbar. |
is_unique | Nicht unterstützt; liefert 422 unique-unsupported-type. |
Abfragefähigkeiten
| Oberfläche | Fähigkeit |
|---|---|
REST filter_operators | contains und is_null (is_null nur bei optionalen Attributen) |
REST is_sortable | false |
| GraphQL-Ausgabe | RecordLinks { primary: RecordLink!, alternatives: [RecordLink!]! } mit RecordLink { url: String!, label: String } |
| GraphQL-Filter | LinksOperators mit _contains und _is_null |
GraphQL order_by | Nicht verfügbar |
| Suche | Bezeichnungen 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.