SemText

Reference · SemText · Data & tables

<sem-data-source>

SemText element

You either write the data inside the element or point at a file with source. Doing both is an error the element reports clearly. With JavaScript off, the data still reads as text.

One named set of data inside a data visualizer. You either write the data inside the element or point at a file with source. Doing both is an error the element reports clearly. With JavaScript off, the data still reads as text. free text — human label rendered as the table `caption`, and the bucket key every query, join and cross-source view reference resolves (exact, then case-insensitive, then normalized: lowercase, non-alphanumeric runs collapsed to `-`, edge `-` trimmed). (optional): one of `table`, `csv`, `yaml`, `json`, `sql` — payload syntax of the body or of the fetched resource; Unknown format is a clear inline error, never a silent blank. (optional): one of `rows`, `yaml-schema` — structure declaration; (absent ⇒ the tier infers). rows ⇒ simple row/column definition via the per-column declaration attribute; yaml-schema ⇒ the payload is an OpenAPI-style YAML document whose nested objects flatten to dotted column paths. (optional): string — with `data-type="rows"`, the per-column declaration, a comma list of `name[:type][?]` (`?` = nullable; types `string`, `number`, `integer`, `boolean`, `date`, `null`). Declared types override inference per column; inference fills any column the declaration omits. (optional): string — URL of a relative/same-origin file or an absolute `http(s)` file/API endpoint; inline payload and `source` are mutually exclusive. `file://` is refused when the document itself is `file://`. (optional): named views as `name=colspec; name=colspec` — `colspec` is `*` or a comma list of column names, matched case-insensitively; malformed segments are skipped (a typo hides a view, it never breaks the document). (optional): view name — the default view. Resolution: `data-view` name ⇒ first declared view ⇒ implicit `all=*`. (optional): one of `true`, `false`; csv only: `false` ⇒ the first row is data and headers synthesize `col-<n>`. (optional): string — `json`/API only: dot/bracket path into a nested response (`data.items`, `rows[2].entries`) that flattens to the row array. (optional): one of `no`; `no` ⇒ skip the in-memory fetch cache (one fetch per URL per page load by default). per the global attribute catalog (conventions.md §2) per the global attribute catalog (conventions.md §2) per the global attribute catalog (conventions.md §2)

Example

sem-data-source.html
source
1 <sem-data-visualizer>
2 <sem-data-source data-name="Token lifetimes" data-format="table"
3 data-views="core=token,max-uses; all=*" data-view="all">
4 | Token | Max uses | Lifetime | Rotates | Since |
5 | :---- | -------: | :------- | :------ | :--------- |
6 | access | 200 | 15 min | true | 2026-01-05 |
7 | id | 1000 | 1 hour | false | 2026-02-14 |
8 </sem-data-source>
9 </sem-data-visualizer>
render

Live render boots with JavaScript — the authored source is alongside.

variant: data-format="csv"

An RFC 4180 payload: quoted fields, `""` escapes, embedded commas and newlines, CRLF. The first record is the header; ragged rows pad with empty cells and drop extras. The table renders with the same caption, typed sort and schema JSON as the default `table` form.

variant: data-format="csv"
sem-data-source-format-csv.html
source
1 <sem-data-visualizer>
2 <sem-data-source data-name="Service ports" data-format="csv">
3 svc,port,ready
4 gateway,443,true
5 search,7700,true
6 </sem-data-source>
7 </sem-data-visualizer>
render

Live render boots with JavaScript — the authored source is alongside.

variant: data-format="csv" data-header="false"

`data-header="false"` (csv only): the first row is data and headers synthesize `col-<n>` — the payload below gains a third row and columns named col-1…col-3. Default is `true`.

variant: data-format="csv" data-header="false"
sem-data-source-format-csv-noheader.html
source
1 <sem-data-visualizer>
2 <sem-data-source data-name="Ad-hoc extract" data-format="csv" data-header="false">
3 access,200,15 min
4 id,1000,1 hour
5 </sem-data-source>
6 </sem-data-visualizer>
render

Live render boots with JavaScript — the authored source is alongside.

variant: data-format="yaml"

The YAML subset (block mappings and sequences, comments, quoted scalars, flow sequences of scalars) — a row payload must be a sequence of mappings; columns are the key union in first-seen order. Flow mappings, anchors, tags and block scalars reject with a clear error naming the construct.

variant: data-format="yaml"
sem-data-source-format-yaml.html
source
1 <sem-data-visualizer>
2 <sem-data-source data-name="Service ports" data-format="yaml">
3 - svc: gateway
4 port: 443
5 ready: true
6 - svc: search
7 port: 7700
8 ready: false
9 </sem-data-source>
10 </sem-data-visualizer>
render

Live render boots with JavaScript — the authored source is alongside.

variant: data-format="json" with data-path

A JSON array of objects is rows; with `data-path="data.items"` the tier first descends the dot/bracket path (`rows[2].entries` indexes too) into the nested response. An unknown path or out-of-range index is a clear error, never a silent blank.

variant: data-format="json" with data-path
sem-data-source-format-json.html
source
1 <sem-data-visualizer>
2 <sem-data-source data-name="Services (API shape)" data-format="json" data-path="data.items">
3 {
4 "status": "ok",
5 "data": {
6 "items": [
7 { "svc": "gateway", "port": 443, "ready": true },
8 { "svc": "search", "port": 7700, "ready": false }
9 ]
10 }
11 }
12 </sem-data-source>
13 </sem-data-visualizer>
render

Live render boots with JavaScript — the authored source is alongside.

variant: data-format="sql" (result-shape declaration)

A `sql` payload is not a result — it declares the shape of one: the projection column names, so the bucket exists for queries and joins before any rows do. The table renders headers-only by design; a non-SELECT statement rejects, and `SELECT *` mirrors the FROM bucket's columns when one is declared in the same container.

variant: data-format="sql" (result-shape declaration)
sem-data-source-format-sql.html
source
1 <sem-data-visualizer>
2 <sem-data-source data-name="Services" data-format="sql">
3 SELECT name, port FROM services WHERE ready = true ORDER BY port LIMIT 5
4 </sem-data-source>
5 </sem-data-visualizer>
render

Live render boots with JavaScript — the authored source is alongside.

variant: data-type="rows" with data-columns

The structure declaration `rows` pins columns with `data-columns="name[:type][?]"` (`?` = nullable). Declared types override per-column inference — `metrics` has an empty `ready` cell, so `ready:boolean?` pins what inference would guess; columns the declaration omits keep their inferred type.

variant: data-type="rows" with data-columns
sem-data-source-rows-declaration.html
source
1 <sem-data-visualizer>
2 <sem-data-source data-name="Service ports" data-format="csv" data-type="rows" data-columns="name:string, port:integer, ready:boolean?">
3 name,port,ready
4 gateway,443,true
5 metrics,9090,
6 </sem-data-source>
7 </sem-data-visualizer>
render

Live render boots with JavaScript — the authored source is alongside.

variant: data-type="yaml-schema"

A `yaml-schema` payload is an OpenAPI-style document: `schema:` declares the row (nested `properties:` flatten to dotted column paths — endpoint.host, endpoint.port), `data:` carries the records. A required property missing from a record warns and leaves the cell null.

variant: data-type="yaml-schema"
sem-data-source-yaml-schema.html
source
1 <sem-data-visualizer>
2 <sem-data-source data-name="Endpoints" data-format="yaml" data-type="yaml-schema">
3 schema:
4 type: array
5 items:
6 type: object
7 properties:
8 svc:
9 type: string
10 endpoint:
11 type: object
12 properties:
13 host:
14 type: string
15 port:
16 type: integer
17 data:
18 - svc: gateway
19 endpoint:
20 host: edge.noizu.com
21 port: 443
22 - svc: search
23 endpoint:
24 host: query.noizu.com
25 port: 7700
26 </sem-data-source>
27 </sem-data-visualizer>
render

Live render boots with JavaScript — the authored source is alongside.

variant: data-view="core" (named view on first paint)

Same payload as the primary, defaulting to the `core` view instead of `all`: only the Token and Max uses columns paint, and every column stays in the DOM with the native `hidden` on excluded cells. Two declared views render the `aria-pressed` button group above the table — pressing All reveals the rest.

variant: data-view="core" (named view on first paint)
sem-data-source-view-core-default.html
source
1 <sem-data-visualizer>
2 <sem-data-source data-name="Token lifetimes" data-views="core=token,max-uses; all=*" data-view="core">
3 | Token | Max uses | Lifetime | Rotates | Since |
4 | :---- | -------: | :------- | :------ | :--------- |
5 | access | 200 | 15 min | true | 2026-01-05 |
6 | id | 1000 | 1 hour | false | 2026-02-14 |
7 </sem-data-source>
8 </sem-data-visualizer>
render

Live render boots with JavaScript — the authored source is alongside.

variant: file/API source (empty body + source)

An empty body plus `source` is the file/API form: the enhance renders a `role="status"` pending region, fetches (one fetch per URL per page load unless `data-cache="no"`), resolves the format (explicit `data-format` wins, then file extension, then sniffing) and renders the table — or a `role="alert"` error naming the cause (fetch failure, non-2xx, parse, CORS). `javascript:`/`data:`/`blob:` schemes are refused; a `file://` document refuses to fetch. Kept Source-only: this deployment serves no /data/tokens.csv, and a 404 would stand in for the success path.

variant: file/API source (empty body + source)
sem-data-source-source-file-load.html
source
1 <sem-data-visualizer>
2 <sem-data-source data-name="Token lifetimes" source="/data/tokens.csv" data-format="csv" data-views="core=token,max-uses; all=*" data-view="all"></sem-data-source>
3 </sem-data-visualizer>
render
No shipped runtime for this element — the authored example renders as plain HTML.

variant: authoring error — inline payload with source

A non-empty body together with `source` is an authoring error and renders a clear `role="alert"` error naming the conflict ("an inline payload and source=… are mutually exclusive — keep one") — never silently resolved. An unknown `data-format` is a clear inline error the same way, never a silent blank.

variant: authoring error — inline payload with source
sem-data-source-error-inline-plus-source.html
source
1 <sem-data-visualizer>
2 <sem-data-source data-name="Token lifetimes" source="/data/tokens.csv">
3 | Token | Lifetime |
4 | :---- | :------- |
5 | access | 15 min |
6 </sem-data-source>
7 </sem-data-visualizer>
render

Live render boots with JavaScript — the authored source is alongside.

Source: spec/schema/sem-data-source.md