(BNotro Software Development.)
Format revision: 3.3
License: Creative Commons Attribution -or- MIT License
SUMMARY
A simple, compact way to represent data tables in a format friendly to both humans and machines, suitable for both file storage and streaming.
An alternative to JSON and XML, suited to simple scenarios, is also intended to be generally compatible with Markdown tables. 3.3
| [Type] | [Weight] | [Cost] |
|---|---|---|
| Apple | 0.1 | $0.10 |
| Pear | .. | .. |
| Banana | 0.2 | $0.30 |
INTRODUCTION
This document presents a simple, compact way to represent data tables in a format friendly to both humans and machines, suitable for both file storage and streaming.
The format is influenced by many existing formats that were reviewed in the process of defining it.
The format has been used successfully in use in a number of real-world projects.
The aims are for compactness, robustness, readability, editability and simplicity of programming needed to parse it.
For simple data requirements this format is well suited as an alternative to the XML, JSON or comma delimited standards. It is designed to export cleanly from Excel (etc.) as a tab delimited file.
The format can also be used for marking or embedding data in text documents as a basic alternative to HTML or Markdown.
REQUIREMENTS and RECOMMENDATIONS
- Requirement: Human readability, machine readability and not getting destroyed (too much) by Excel and text editors (automatic tab-to-space conversion is not friendly to this).
- Requirement: All header rows must start with a left-square-bracket
- Requirement: All header keys are enclosed within square brackets [thus].
- Requirement: A header row only contains headers
- Requirement: Multiple headers within a row are separated by a delimiter character (e.g. tab 0x9 or vertical-bar 0x7c)
- Requirement: A subsequent header row marks the start of a new table
- Requirement: Value rows/columns follow a header row
- Requirement: Values may be omitted (and are filled in during processing as empty strings) - that is, data rows may be ragged.
- Requirement: Excess values are ignored and not read (value columns with no corresponding header)
- Requirement: Any headers from a previous table are ignored.
- Requirement: Duplicate headers within a table are ignore (the whole column)
- Requirement: The delimiter between the first two header cells of a table is assumed to be that used for the entire rest of the table. This is a simple way to work with various delimiters. Typically this will be a tab 0x09 or the vertical bar | 0x7C
- Recommendation: A cell value equal to two period marks only ( .. 0x2e2e) is a ditto mark that copies the value of previous value (above) in that column. The ditto mark in a first row is parsed as an empty string. This is fast to type and is not destroyed by Excel, etc.
- Recommendation: Initial rows prior to any header row are to be parsed as a table with an empty string as the implied header key.
- Recommendation: Header names are only alphanumeric or spaces.
- Recommendation: There are no reserved header key names -- this is up to the receiver of the assembled/parsed data to build on top of this standard (and separate from it)
- Recommendation: Any relationships between multiple tables in a file is completely arbitrary and up to the receiver of the assembled/parsed data.
- Recommendation: When Table Data Notation is used as an extension to the Markdown standard, it should ideally replace all other table format extensions -or- also recognise and process the most common Markdown table format extension.3.3
KNOWN WEAKNESSES
Currently there is no standard way to include delimiters within values (no delimiter escape mechanism)
This could be done grep (backslash…) and/or possibly html (ampersand character-name semicolon), but has not been a requirement yet. Suggestions welcome.
Deliberately there is no structural nesting, as per HTML: <i><b>value</b></i>
Deliberately there is no equivalent to HTML attributes thusly: <a href=url>
| [EXAMPLES] | ||||
| Here are a few examples to demonstrate the format. | ||||
| [Creature] | ||||
| Cat | ||||
| Dog | ||||
| Parrot | ||||
| Fish | ||||
| [Type] | [Weight] | [Cost] | ||
| Apple | 0.1 | $0.10 | ||
| Banana | 0.2 | $0.30 | ||
| Pear | 0.15 | $0.15 | ||
| [Person] | [Score] | [Note] | ||
| Bob | 10 | |||
| Bob | 40 | |||
| Alice | 90 | |||
| Bob | .. | 90 score | ||
| Mary | 40 | |||
| Alice | 83 | |||
| [X] | [Y] | [Z] | [A] | [Note] |
| No result | ||||
| 4 | 2 | |||
| 2 | 4 | |||
| No result | ||||
| 0 | ||||
| 1 | 2 | 2 | ||
| 3 | 4 | |||
| [Id] | [space] | [m2] | [Note] | |
| 1 | Cattleyard | 50 | ||
| 2 | .. | 100 | Cattleyard space too | |
| 3 | .. | 120 | ditto | |
| 4 | .. | 70 | ditto | |
| 5 | Office | 16 | ||
| 6 | .. | 12 | Office space too | |
| 7 | .. | 10 | ditto | |
| [Table] | ||||
| Meat | ||||
| [Name] | [Cost] | |||
| Beef | $3.50 | |||
| Ham | $2.00 | |||
| Turkey | $2.50 | |||
AUTHOR
Andrew Kingdom, BNotro Software Development © 2017-2022
SOURCE CODE EXAMPLES