Sample files¶
The format of a sample file, key by key.
The file¶
A sample is one Markdown file, .md, .MD or .markdown:
---
schema_version: 1
name: steel-01
tags: [reference]
material: steel
operators: [ana, tom]
tested: 2026-03-04
properties:
width: {v: 12.513, u: 0.01, unit: mm}
thickness: {v: 2.0, unit: mm}
tables:
curve:
index: strain
columns:
strain: {unit: "%"}
force: {unit: kN}
rows:
- strain: 0
force: 0.0
- strain: 0.2
force: 9.516
---
# steel-01
The note: free Markdown.
Part |
What it is |
|---|---|
frontmatter |
The YAML between the first two |
note |
Everything after the second |
Top-level keys¶
Key |
Holds |
Written |
|---|---|---|
|
The format's version: |
Always |
|
The sample's name; without it, the file name without its extension |
When set |
|
A list of tags |
When not empty |
any other key |
An attribute |
When set |
|
The properties, by name |
When not empty |
|
The tables, by name |
When not empty |
Keys are written in this order: schema_version, name, tags, the
attributes in their order, properties, tables.
A version this build does not support is refused, naming both versions. An unknown key inside a property, a table or a column is refused.
Names¶
A name, of a property, a table, a column, an attribute or a tag, starts with
a letter (or _, for a tag alone) and continues with letters, digits and _. Letters of every
alphabet count: température, épaisseur. A hyphen, a dot or a space is not
allowed, nor a digit first.
A property, a table and an attribute share one set of names: one name is one of them.
A property, table, column or attribute name cannot begin with
_: a leading_is kept for Python's private state.Reserved, and refused as a property, table or attribute name:
name,tags,path,filename,readings,project,state,note(the text below the frontmatter:set note=and Python'ssample.notewrite it).
Scalars¶
Written |
Read as |
|---|---|
|
A number |
|
A boolean |
|
A date |
|
A date and time, written with |
|
Not applicable: the value does not apply to this sample |
anything else |
Text |
yes, no and a quoted number, "12.5", are text.
Attributes¶
An attribute is one scalar, or a list of scalars of one kind (numbers, dates, text or booleans; integers and decimals mix, as do dates and date-times). It has no unit, uncertainty or readings. A mapping is not an attribute: a top-level key holding one is refused.
material: steel
tested: 2026-03-04
operators: [ana, tom]
Links¶
A text attribute may lead elsewhere: to another sample, to a file, or to a web page. Two forms are read, the one Obsidian writes and the one Markdown does:
reference: "[[aluminium-01]]"
twin: "[[copper-01|the copper]]"
cut_from: "[plate P3](../plates/P3.md)"
certificate: "[certificate](../certificates/S355-0425.pdf)"
method: "[the method](../papers/method.pdf#page=12)"
curve: "[[curve.csv]]"
datasheet: "[datasheet](https://example.org/s355)"
standard: https://example.org/iso-6892
source: zotero://select/library/items/ABCD1234
parents: ["[[aluminium-01]]", "[[copper-01]]"]
[[NAME]]names a sample of the project, as Obsidian finds a note: the one whose file isNAME.md, or, where no file is named so, the one whosenameis NAME; written as it is first, then in any case.[[NAME.md]]names it too, and[[2024/NAME]]the one under a folder2024, where two samples have one name. After|comes what Obsidian shows in its place; a heading after#is ignored, and the sample opened whole.[[FILE]], a name with its extension, names any other file of the project, wherever it lies:[[curve.csv]],[[method.pdf]];[[2024/curve.csv]]where two files have one name.[text](path)names a file by its path from the sample's own folder, as Markdown reads a link: a sample, of this project or another, or any file, a certificate, a raw data file, a folder. A space in the path is written%20, or the path between<and>. Write it with/, as Obsidian does; a\is read as/on every system. A place in the file after#is kept apart from the path:report.md#resultsisreport.md.A PDF at a page,
[the method](method.pdf#page=12)or[[method.pdf#page=12]], opens at that page in the web browser, which every system's browser does; a PDF reader opened by the system is given no page. Where no browser is found, the PDF opens at its start, and that is said.https://…, alone or as[text](https://…), names a web page; so dohttp://andftp://. The addresses of other tools are links too, opened by the application that answers to them:zotero://(a reference in Zotero),obsidian://,mailto:,file://.A list of links names several: the samples a specimen was made from.
The quotes are needed: unquoted, a link reads as a list, and the file is
refused at that line, with the quoted form to write. set reference=[[aluminium-01]] writes them, and set parents=[[aluminium-01]],[[copper-01]] writes a list of two; after [[, Tab
offers the project's samples.
A link is text a filter and an export read as written. It is shown as
Markdown shows one, in the terminal interface and in a table drawn in a
terminal: its text alone, the copper for [[copper-01|the copper]],
underlined in the link colour; so does view in a terminal. A web page is
marked ↗; a link leading nowhere is marked ✗, in the error colour. Typed, a link is the text as
written; a table written to a file or a pipe keeps it so.
In the terminal interface, Enter or o on a link opens where it leads: a
sample on its screen, even one the filter leaves out or of another project,
a file in its application, a page in the browser; on a list, Enter opens
its items, and Enter or o follows the one under the cursor. A sample's
screen ends with the samples linking to it, linked from, each followed by
Enter. On the command line, the filter links to NAME selects the samples
whose links write NAME (filters). From
Python, sample.linked("reference") reads the sample, a file that is no
sample gives its path, a pathlib.Path, and a list of links gives a list.
validate reports a link that leads to no sample or to several, and a path
where nothing is; a web page, and another tool's address, are not checked.
samplekit FILE rename NEW renames a sample and keeps its links: the file,
its own files under [collection] files (a folder named after it too), its
name where it was the file's name, and every link of the project leading to
it, [[old]] and [text](old.md) alike, each as it was written:
[[2024/OLD.md#Notes|the notes]] keeps its folder, its extension, its
heading and its text.
Obsidian makes only [[…]] clickable among a note's properties: there, a
Markdown link stays text. Link samples walks
through them on the tensile example.
Properties¶
A property holds a value, and its uncertainty, unit and readings where it has them. With a value alone it is a bare scalar; otherwise a mapping:
properties:
specimens_cut: 3
width: {v: 12.513, u: 0.010, unit: mm}
thickness: {v: 2.0, unit: mm}
gauge_length: n/a
Key |
Holds |
|---|---|
|
The value: a scalar |
|
Repeated measurements of the property: a list of numbers |
|
The standard uncertainty, in the value's unit: a number |
|
The unit, as written; never converted |
|
The symbol, over the one |
|
Which statistic of the readings is the value, and which the uncertainty |
|
For a computed value: what it was computed from |
|
A digest of the property's value, uncertainty and readings |
Keys are written in this order.
A file holds no precision:
precisionis refused, and declared in.samplekitrc's[property.*].vanduare the only spellings.valueanduncertainty, in a property, a cell,statisticsorcomputed, are refused, the file not read:validatenames the key, and the keys expected in its place.n/ahas no uncertainty.Readings with neither
vnor a statistic have no value.A
vbeside readings is the value. With acomputedrecord namingreadings, the statistic gave it; without one, it was written by hand.
statistics¶
thickness:
v: 2.0023333333333335
readings: [1.995, 2.004, 2.008]
u: 0.003844187531556873
unit: mm
statistics: {v: mean, u: standard_error}
computed: {readings: 3160016f6c6e}
fingerprint: 1d88e7bb89d3
Key |
Statistics |
|---|---|
|
|
|
|
computed¶
A computed property records each input it was read from, with that input's fingerprint at the time.
Form |
Means |
|---|---|
|
Computed, value and uncertainty, from these inputs |
|
Computed from no input |
|
Only the value computed, from these inputs |
|
Only the uncertainty computed, from no input |
|
Inputs every formula read, then one channel's own |
|
The statistic of the property's own readings |
|
An attribute input, recorded as its value |
|
An input whose value was written by hand over its formula |
Input names:
Name |
Input |
|---|---|
|
A property, or an attribute |
|
A whole column of a table |
|
In a table cell: the same row's cell of that column |
|
The property's own readings |
fingerprint¶
Twelve hexadecimal digits, a digest of the property's value, uncertainty and
readings, not its unit. Written on a property that is computed or that
something is computed from. fingerprint: {edited: …} marks a value written
by hand over its formula, and fingerprint: {failed: ValueError} a value whose
formula raised that error when last run, the number kept the last it gave.
Fingerprints gives the recipe, to compute one again by
hand.
Tables¶
tables:
curve:
title: "The force read at each strain"
index: strain
columns:
strain: {unit: "%"}
force: {unit: kN, statistics: {v: mean, u: standard_error}}
grips: {}
rows:
- strain: 0
force: 0.0
grips: wedge
- strain: 0.2
force: {readings: [9.51, 9.52]}
grips: wedge
Key |
Holds |
|---|---|
|
A title, as text |
|
The column that tells rows apart, or a list of columns: |
|
Each column, in order: |
|
The rows, in order: each maps a column to a cell |
A cell has the form of a property: a number, with optionally an uncertainty, readings and a unit; or a text, a date,
trueorfalse, as an attribute is:grips: wedge. One table may hold both, a column of text beside a column of forces. Its column declaresstatisticsonce for every cell; a cell may write its own, which it keeps, and which wins over its column's.Rows are written with their cells in column order, one line per cell.
A table whose index repeats a value is set aside, reported by
validate, and the sample is not written until it is repaired.
Fields¶
How a filter, a column, a sort and Python name a part of a sample.
Field |
Means |
|---|---|
|
The value of the property |
|
The same |
|
Its uncertainty |
|
Its unit |
|
A statistic of its readings: |
|
An attribute |
|
The first item of a list attribute, |
|
The cell of column |
|
That cell's uncertainty |
|
A cell at an index holding a space |
|
A cell of a table indexed by two columns |
|
In a filter: a cell of the column, in any row, holds it |
|
In a filter: any cell of the table holds it |
|
In a filter: one row meets the condition, each name its cell in that row |
|
The fourth row, by position; |
|
The sample's name and tags |
|
Where the sample is stored |
|
The name of the folder of the sample's project |
|
How the sample stands: |
Writing¶
SampleKit writes a file only when asked: a command's change answered y, or
written with --write; a change confirmed in the TUI; save() in Python.
The frontmatter is written in one fixed form: the key order above, numbers in one spelling, a property carrying a
computedrecord on several lines, one key a line, and any other property, as every cell of a table, on one line however long.Comments in the frontmatter are not kept.
What SampleKit reads otherwise than it is written is changed by the next write: a key whose value is
nullis removed, a YAML tag (!!python/…) dropped, an uncertainty besiden/adropped, and a date no calendar has (2026-02-30) kept as the text it was read as.validatenotes each, and a command's preview says which this write changes.The note is kept byte for byte, unless you replace it,
set note=….A file is written to a temporary file, then put in place. A file changed since it was read, or read-only, is not written. A write that changes nothing is not made.
A file written by SampleKit 0.2 is not read, and no command converts it.