.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). MIME type: application/x-posprint (registered via packaging/mime/posprint.xml; claimed by *.pos)
---
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, \n line endings normalized on load) |
---
Metadata schema (version 1)
{
"title": "Sales Receipt",
"page_width_mm": 80,
"preview_mode": "autoscale",
"chars_per_line": 48,
"codepage": "CP437",
"cut_after_print": true
}
| Field | Type | Default | Description | |
|---|---|---|---|---|
title | string? | null | Display name in app title / recent files | |
page_width_mm | number | 80 | Physical paper width: 58 or 80 (others allowed) | |
preview_mode | "autoscale" \ | "fixed" | "autoscale" | How preview panel sizes content |
chars_per_line | number? | derived | Override character width for preview; derived from mm if omitted | |
codepage | string? | "CP437" | Character encoding for ESC/POS text | |
cut_after_print | boolean | true | Append cut command when printing if doc has no @cut |
Page width derivation
page_width_mm | Typical dots (203 DPI) | Default chars_per_line (Font A) |
|---|---|---|
| 58 | 384 | 32 |
| 80 | 576 | 48 |
---
Example file
receipt.pos:
{
"version": 1,
"metadata": {
"title": "Standard Receipt",
"page_width_mm": 80,
"preview_mode": "autoscale",
"codepage": "CP437",
"cut_after_print": true
},
"body": "# ${StoreName}\n:center:\n\nReceipt: ${DocumentNumber}\n\n---\n\n:right:\n**TOTAL: ${GrandTotal}**\n\n@barcode CODE128 ${DocumentNumber}\n@feed 4\n@cut\n"
}
For readability, the app may save body with literal newlines (pretty-printed JSON) when the user chooses “formatted save”; both pretty and escaped forms are valid.
---
Asset resolution
- Paths in
@imagedirectives are resolved relative to the directory containing the.posfile unless absolute. - Bundled assets: optional
assets/subfolder next to the template. - Parameterized image paths (
${LogoPath}) resolve after substitution; relative paths still anchor to the.posfile directory.
---
Version migration
| From | To | Migration |
|---|---|---|
| — | 1 | Initial release |
On load, if version is newer than app supports → error with upgrade message. If older → run migration chain (none yet).
---
Alternative considered: two-file bundle
Rejected for v1: .pos + sidecar .pos.json adds friction. Single JSON file keeps save/load atomic.
A future .poszip could bundle images for portable templates.
---
Validation rules
On save:
versionmust equal supported versionpage_width_mm> 0bodymust be valid UTF-8
On load:
- Parse JSON; validate schema
- Parse
bodywith DSL parser; warnings shown in UI but file still loads
---
TypeScript / Rust types (reference)
interface PosFile {
version: number;
metadata: PosMetadata;
body: string;
}
interface PosMetadata {
title?: string;
page_width_mm: number;
preview_mode: "autoscale" | "fixed";
chars_per_line?: number;
codepage?: string;
cut_after_print?: boolean;
}
Rust types use serde derive in src/io/mod.rs and are used directly by the egui app (no IPC layer).
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 | **MIME type:** `application/x-posprint` (registered via `packaging/mime/posprint.xml`; claimed by `*.pos`) |
| 7 | |
| 8 | |
| 9 | --- |
| 10 | |
| 11 | ## Top-level schema |
| 12 | |
| 13 | ```json |
| 14 | { |
| 15 | "version": 1, |
| 16 | "metadata": { ... }, |
| 17 | "body": "..." |
| 18 | } |
| 19 | ``` |
| 20 | |
| 21 | | Field | Type | Required | Description | |
| 22 | |-------|------|----------|-------------| |
| 23 | | `version` | `number` | yes | File format version (currently `1`) | |
| 24 | | `metadata` | `object` | yes | Document settings | |
| 25 | | `body` | `string` | yes | DSL source (UTF-8, `\n` line endings normalized on load) | |
| 26 | |
| 27 | --- |
| 28 | |
| 29 | ## Metadata schema (version 1) |
| 30 | |
| 31 | ```json |
| 32 | { |
| 33 | "title": "Sales Receipt", |
| 34 | "page_width_mm": 80, |
| 35 | "preview_mode": "autoscale", |
| 36 | "chars_per_line": 48, |
| 37 | "codepage": "CP437", |
| 38 | "cut_after_print": true |
| 39 | } |
| 40 | ``` |
| 41 | |
| 42 | | Field | Type | Default | Description | |
| 43 | |-------|------|---------|-------------| |
| 44 | | `title` | `string?` | `null` | Display name in app title / recent files | |
| 45 | | `page_width_mm` | `number` | `80` | Physical paper width: `58` or `80` (others allowed) | |
| 46 | | `preview_mode` | `"autoscale"` \| `"fixed"` | `"autoscale"` | How preview panel sizes content | |
| 47 | | `chars_per_line` | `number?` | derived | Override character width for preview; derived from mm if omitted | |
| 48 | | `codepage` | `string?` | `"CP437"` | Character encoding for ESC/POS text | |
| 49 | | `cut_after_print` | `boolean` | `true` | Append cut command when printing if doc has no `@cut` | |
| 50 | |
| 51 | ### Page width derivation |
| 52 | |
| 53 | | `page_width_mm` | Typical dots (203 DPI) | Default `chars_per_line` (Font A) | |
| 54 | |-----------------|------------------------|-----------------------------------| |
| 55 | | 58 | 384 | 32 | |
| 56 | | 80 | 576 | 48 | |
| 57 | |
| 58 | --- |
| 59 | |
| 60 | ## Example file |
| 61 | |
| 62 | **`receipt.pos`:** |
| 63 | |
| 64 | ```json |
| 65 | { |
| 66 | "version": 1, |
| 67 | "metadata": { |
| 68 | "title": "Standard Receipt", |
| 69 | "page_width_mm": 80, |
| 70 | "preview_mode": "autoscale", |
| 71 | "codepage": "CP437", |
| 72 | "cut_after_print": true |
| 73 | }, |
| 74 | "body": "# ${StoreName}\n:center:\n\nReceipt: ${DocumentNumber}\n\n---\n\n:right:\n**TOTAL: ${GrandTotal}**\n\n@barcode CODE128 ${DocumentNumber}\n@feed 4\n@cut\n" |
| 75 | } |
| 76 | ``` |
| 77 | |
| 78 | For readability, the app may save `body` with literal newlines (pretty-printed JSON) when the user chooses “formatted save”; both pretty and escaped forms are valid. |
| 79 | |
| 80 | --- |
| 81 | |
| 82 | ## Asset resolution |
| 83 | |
| 84 | - Paths in `@image` directives are resolved relative to the **directory containing the `.pos` file** unless absolute. |
| 85 | - Bundled assets: optional `assets/` subfolder next to the template. |
| 86 | - Parameterized image paths (`${LogoPath}`) resolve after substitution; relative paths still anchor to the `.pos` file directory. |
| 87 | |
| 88 | --- |
| 89 | |
| 90 | ## Version migration |
| 91 | |
| 92 | | From | To | Migration | |
| 93 | |------|-----|-----------| |
| 94 | | — | 1 | Initial release | |
| 95 | |
| 96 | On load, if `version` is newer than app supports → error with upgrade message. |
| 97 | If older → run migration chain (none yet). |
| 98 | |
| 99 | --- |
| 100 | |
| 101 | ## Alternative considered: two-file bundle |
| 102 | |
| 103 | Rejected for v1: `.pos` + sidecar `.pos.json` adds friction. Single JSON file keeps save/load atomic. |
| 104 | |
| 105 | A future `.poszip` could bundle images for portable templates. |
| 106 | |
| 107 | --- |
| 108 | |
| 109 | ## Validation rules |
| 110 | |
| 111 | On save: |
| 112 | |
| 113 | - `version` must equal supported version |
| 114 | - `page_width_mm` > 0 |
| 115 | - `body` must be valid UTF-8 |
| 116 | |
| 117 | On load: |
| 118 | |
| 119 | - Parse JSON; validate schema |
| 120 | - Parse `body` with DSL parser; warnings shown in UI but file still loads |
| 121 | |
| 122 | --- |
| 123 | |
| 124 | ## TypeScript / Rust types (reference) |
| 125 | |
| 126 | ```typescript |
| 127 | interface PosFile { |
| 128 | version: number; |
| 129 | metadata: PosMetadata; |
| 130 | body: string; |
| 131 | } |
| 132 | |
| 133 | interface PosMetadata { |
| 134 | title?: string; |
| 135 | page_width_mm: number; |
| 136 | preview_mode: "autoscale" | "fixed"; |
| 137 | chars_per_line?: number; |
| 138 | codepage?: string; |
| 139 | cut_after_print?: boolean; |
| 140 | } |
| 141 | ``` |
| 142 | |
| 143 | Rust types use `serde` derive in `src/io/mod.rs` and are used directly by the egui app (no IPC layer). |