.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 (suggested): application/vnd.posprint+json
---
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,
"chars_per_line": 48,
"codepage": "CP437"
}
| 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 |
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,
"codepage": "CP437"
},
"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).
---
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;
}
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 (suggested):** `application/vnd.posprint+json` |
| 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, `\n` line endings normalized on load) | |
| 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 / recent files | |
| 42 | | `page_width_mm` | `number` | `80` | Physical paper width: `58` or `80` (others allowed) | |
| 43 | | `preview_mode` | `"autoscale"` \| `"fixed"` | `"autoscale"` | How preview panel sizes content | |
| 44 | | `chars_per_line` | `number?` | derived | Override character width for preview; derived from mm if omitted | |
| 45 | | `codepage` | `string?` | `"CP437"` | Character encoding for ESC/POS text | |
| 46 | |
| 47 | ### Page width derivation |
| 48 | |
| 49 | | `page_width_mm` | Typical dots (203 DPI) | Default `chars_per_line` (Font A) | |
| 50 | |-----------------|------------------------|-----------------------------------| |
| 51 | | 58 | 384 | 32 | |
| 52 | | 80 | 576 | 48 | |
| 53 | |
| 54 | --- |
| 55 | |
| 56 | ## Example file |
| 57 | |
| 58 | **`receipt.pos`:** |
| 59 | |
| 60 | ```json |
| 61 | { |
| 62 | "version": 1, |
| 63 | "metadata": { |
| 64 | "title": "Standard Receipt", |
| 65 | "page_width_mm": 80, |
| 66 | "codepage": "CP437" |
| 67 | }, |
| 68 | "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" |
| 69 | } |
| 70 | ``` |
| 71 | |
| 72 | 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. |
| 73 | |
| 74 | --- |
| 75 | |
| 76 | ## Asset resolution |
| 77 | |
| 78 | - Paths in `@image` directives are resolved relative to the **directory containing the `.pos` file** unless absolute. |
| 79 | - Bundled assets: optional `assets/` subfolder next to the template. |
| 80 | - Parameterized image paths (`${LogoPath}`) resolve after substitution; relative paths still anchor to the `.pos` file directory. |
| 81 | |
| 82 | --- |
| 83 | |
| 84 | ## Version migration |
| 85 | |
| 86 | | From | To | Migration | |
| 87 | |------|-----|-----------| |
| 88 | | — | 1 | Initial release | |
| 89 | |
| 90 | On load, if `version` is newer than app supports → error with upgrade message. |
| 91 | If older → run migration chain (none yet). |
| 92 | |
| 93 | --- |
| 94 | |
| 95 | ## Validation rules |
| 96 | |
| 97 | On save: |
| 98 | |
| 99 | - `version` must equal supported version |
| 100 | - `page_width_mm` > 0 |
| 101 | - `body` must be valid UTF-8 |
| 102 | |
| 103 | On load: |
| 104 | |
| 105 | - Parse JSON; validate schema |
| 106 | - Parse `body` with DSL parser; warnings shown in UI but file still loads |
| 107 | |
| 108 | --- |
| 109 | |
| 110 | ## TypeScript / Rust types (reference) |
| 111 | |
| 112 | ```typescript |
| 113 | interface PosFile { |
| 114 | version: number; |
| 115 | metadata: PosMetadata; |
| 116 | body: string; |
| 117 | } |
| 118 | |
| 119 | interface PosMetadata { |
| 120 | title?: string; |
| 121 | page_width_mm: number; |
| 122 | preview_mode: "autoscale" | "fixed"; |
| 123 | chars_per_line?: number; |
| 124 | codepage?: string; |
| 125 | } |
| 126 | ``` |
| 127 | |
| 128 | Rust types use `serde` derive in `src/io/mod.rs` and are used directly by the egui app (no IPC layer). |