Skip to content
Source on GitHubVisitors

12. Routing

Contents of FBL 0.17

12.1 Claims

A binding's claims say which files it takes:

Property Type Description
extensions string[] Lowercase, with the dot (.tml, .ttl). Matched ignoring case.
names glob[] File names claimed whatever their extension (databricks.yml, Chart.yaml).
shared bool The extension belongs to many formats (.yml, .json). A shared binding MUST have a marker or be registrationOnly.
marker Marker The opt-in mark a file needs before this binding claims it (section 12.2).
registrationOnly bool The binding never claims a bare file; the file opens only through a registration.
suggest {contains} Substrings of a body's first 64 KiB that make a host propose this binding (section 12.3).
origins string[] The origins of the tool types that share this binding; each is the language.origin of a specification whose persistence names it.
readings map origin → {bare, suggest} For a shared binding: which reading a bare file opens as (bare, at most one) and what suggests each reading.

12.2 Markers

A marker is one of: {rootKey, value?}, a root key a yaml or json body must have (with that value, if given); {firstLine}, a prefix the first line must start with, after a byte-order mark; {pattern, lines?}, an expression one of the first lines lines (default 20) must match, line 1 after a byte-order mark. A host evaluates a marker on the body's bytes without reading it through the binding.

12.3 Routing a file

When the user opens a file that is not a registration, the host routes it:

  1. The candidates are the bindings of installed tool types whose names match the file name, or whose extensions include its extension; a registrationOnly binding is not a candidate, and a shared one is a candidate only if its marker matches.
  2. With one candidate, the file opens as it: as its bare reading when the binding has readings, or as its only tool type.
  3. With several, the host offers them all and MUST NOT choose silently; with none, the file is not a diagram.

When the user opens a registration, line 1 decides the tool type (section 8.1). When the user asks to add a diagram for a file (a host's "Add" or "Open as"), the host MAY propose every binding whose suggest matches the file's content, first those whose reading's suggest matches; accepting one creates a registration. A host MAY also offer to add a binding's marker to a file that lacks it; it adds the marker only when the user agrees, as a splice (an insert-key of the root key after the last root key, or an inserted first line), which is one edit that can be undone.

12.4 Replacing x-adp routing keys (informative)

The routing keys today's definitions keep in x-adp map to claims: claimsBareFiles is readings.<origin>.bare; sharedExtension and x-adp-shared-extension are shared; suggestWhenBodyContains is suggest.contains; documentExtensions is extensions; subject: folder is body.kind: "folder"; registrationHeaders is registration.headers; x-adp-origin is DISL's language.origin.

Referenced from