.pos file format
A .pos file stores a POS print template: metadata (page settings, title) plus the DSL document body as plain text.
Format: JSON envelope with a .pos extension (human-readable, git-friendly). Installed MIME type: application/x-posprint (see packaging MIME XML).
---
Top-level schema
{
"version": 1,
"metadata": { ... },
"body": "..."
}
| Field | Type | Required | Description |
|---|---|---|---|
version | number | yes | File format version (currently 1) |
metadata | object | yes | Document settings |
body | string | yes | DSL source (UTF-8) |
---
Metadata schema (version 1)
{
"title": "Sales Receipt",
"page_width_mm": 80,
"chars_per_line": 48,
"codepage": "CP437"
}
| Field | Type | Default | Description |
|---|---|---|---|
title | string? | null | Display name in app title |
page_width_mm | number | 80 | Physical paper width (mm) |
chars_per_line | number? | derived | Override column count; derived from mm if omitted |
codepage | string? | "CP437" | Reserved; encoder uses CP437 today |
Printable width model
Effective print/preview width uses Font A columns:
printable_dots = chars_per_line() × 12
page_width_mm | Default chars_per_line | printable_dots |
|---|---|---|
| ≤ 58 | 32 | 384 |
| > 58 | 48 | 576 |
Legacy fields (ignored)
Unknown JSON keys are ignored by serde. Notably:
| Field | Former meaning | Current behaviour |
|---|---|---|
preview_mode | autoscale / fixed preview | Ignored; UI uses zoom slider |
cut_after_print | auto-cut after job | Ignored; use @cut in the template |
---
Example file
receipt.pos:
{
"version": 1,
"metadata": {
"title": "Standard Receipt",
"page_width_mm": 80,
"codepage": "CP437"
},
"body": "# ${StoreName}\n:center:\n\nReceipt: ${DocumentNumber}\n\n---\n\n:right:\nTOTAL: ${GrandTotal}\n\n@barcode CODE128 ${DocumentNumber}\n@feed 4\n@cut\n"
}
---
Asset resolution
- Paths in
@imageresolve relative to the directory containing the.posfile unless absolute. - Parameterized paths (
${LogoPath}) resolve after substitution; relative paths still anchor to the.posdirectory.
---
Version migration
| From | To | Migration |
|---|---|---|
| — | 1 | Initial release |
On load, if version is newer than the app supports → error. Older versions would migrate (none yet).
---
Validation
On save / load: JSON parse, version == 1, page_width_mm > 0, UTF-8 body. DSL parse errors show in the UI; the file can still load.
---
Rust types
Defined in src/io/mod.rs (PosFile, PosMetadata) with serde derive. Used directly by the egui app (no IPC).
Source
| 1 | # `.pos` file format |
| 2 | |
| 3 | A `.pos` file stores a POS print template: metadata (page settings, title) plus the DSL document body as plain text. |
| 4 | |
| 5 | **Format:** JSON envelope with a `.pos` extension (human-readable, git-friendly). |
| 6 | **Installed MIME type:** `application/x-posprint` (see packaging MIME XML). |
| 7 | |
| 8 | --- |
| 9 | |
| 10 | ## Top-level schema |
| 11 | |
| 12 | ```json |
| 13 | { |
| 14 | "version": 1, |
| 15 | "metadata": { ... }, |
| 16 | "body": "..." |
| 17 | } |
| 18 | ``` |
| 19 | |
| 20 | | Field | Type | Required | Description | |
| 21 | |-------|------|----------|-------------| |
| 22 | | `version` | `number` | yes | File format version (currently `1`) | |
| 23 | | `metadata` | `object` | yes | Document settings | |
| 24 | | `body` | `string` | yes | DSL source (UTF-8) | |
| 25 | |
| 26 | --- |
| 27 | |
| 28 | ## Metadata schema (version 1) |
| 29 | |
| 30 | ```json |
| 31 | { |
| 32 | "title": "Sales Receipt", |
| 33 | "page_width_mm": 80, |
| 34 | "chars_per_line": 48, |
| 35 | "codepage": "CP437" |
| 36 | } |
| 37 | ``` |
| 38 | |
| 39 | | Field | Type | Default | Description | |
| 40 | |-------|------|---------|-------------| |
| 41 | | `title` | `string?` | `null` | Display name in app title | |
| 42 | | `page_width_mm` | `number` | `80` | Physical paper width (mm) | |
| 43 | | `chars_per_line` | `number?` | derived | Override column count; derived from mm if omitted | |
| 44 | | `codepage` | `string?` | `"CP437"` | Reserved; encoder uses CP437 today | |
| 45 | |
| 46 | ### Printable width model |
| 47 | |
| 48 | Effective print/preview width uses Font A columns: |
| 49 | |
| 50 | `printable_dots = chars_per_line() × 12` |
| 51 | |
| 52 | | `page_width_mm` | Default `chars_per_line` | `printable_dots` | |
| 53 | |-----------------|--------------------------|------------------| |
| 54 | | ≤ 58 | 32 | 384 | |
| 55 | | > 58 | 48 | 576 | |
| 56 | |
| 57 | ### Legacy fields (ignored) |
| 58 | |
| 59 | Unknown JSON keys are ignored by serde. Notably: |
| 60 | |
| 61 | | Field | Former meaning | Current behaviour | |
| 62 | |-------|----------------|-------------------| |
| 63 | | `preview_mode` | autoscale / fixed preview | Ignored; UI uses zoom slider | |
| 64 | | `cut_after_print` | auto-cut after job | Ignored; use `@cut` in the template | |
| 65 | |
| 66 | --- |
| 67 | |
| 68 | ## Example file |
| 69 | |
| 70 | **`receipt.pos`:** |
| 71 | |
| 72 | ```json |
| 73 | { |
| 74 | "version": 1, |
| 75 | "metadata": { |
| 76 | "title": "Standard Receipt", |
| 77 | "page_width_mm": 80, |
| 78 | "codepage": "CP437" |
| 79 | }, |
| 80 | "body": "# ${StoreName}\n:center:\n\nReceipt: ${DocumentNumber}\n\n---\n\n:right:\nTOTAL: ${GrandTotal}\n\n@barcode CODE128 ${DocumentNumber}\n@feed 4\n@cut\n" |
| 81 | } |
| 82 | ``` |
| 83 | |
| 84 | --- |
| 85 | |
| 86 | ## Asset resolution |
| 87 | |
| 88 | - Paths in `@image` resolve relative to the **directory containing the `.pos` file** unless absolute. |
| 89 | - Parameterized paths (`${LogoPath}`) resolve after substitution; relative paths still anchor to the `.pos` directory. |
| 90 | |
| 91 | --- |
| 92 | |
| 93 | ## Version migration |
| 94 | |
| 95 | | From | To | Migration | |
| 96 | |------|-----|-----------| |
| 97 | | — | 1 | Initial release | |
| 98 | |
| 99 | On load, if `version` is newer than the app supports → error. Older versions would migrate (none yet). |
| 100 | |
| 101 | --- |
| 102 | |
| 103 | ## Validation |
| 104 | |
| 105 | On save / load: JSON parse, `version == 1`, `page_width_mm > 0`, UTF-8 body. DSL parse errors show in the UI; the file can still load. |
| 106 | |
| 107 | --- |
| 108 | |
| 109 | ## Rust types |
| 110 | |
| 111 | Defined in `src/io/mod.rs` (`PosFile`, `PosMetadata`) with `serde` derive. Used directly by the egui app (no IPC). |