Add JSON schema for rec_info output

.github/workflows/test-schemas.yml

@@ -0,0 +1,36 @@
+name: Test schemas
+
+on:
+  push:
+    branches: [main]
+
+  pull_request:
+    branches: [main]
+
+  workflow_dispatch:
+
+jobs:
+  run:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+
+      - name: Verify schemas up-to-date
+        run: |
+          python3 utils/gen_schema.py
+
+          if [ -n "$(git status --porcelain)" ]; then
+            echo "::error:: Uncommited schema changes. Please run 'python3 utils/gen_schema.py' locally and commit the changes."
+            exit 1
+          fi

docs_src/examples.md

@@ -2,7 +2,7 @@
 The OpenPrintTag specification comes with [a set of utilities written in Python]({{repo}}/tree/main/utils) that serve as a baseline/reference implementation.
 
 ## Reading a tag
-The `rec_info` utility can be used to parse data on the NFC tag into a YAML file that is readable by both humans and computers.
+The `rec_info` utility can be used to parse data on the NFC tag into a YAML file that is readable by both humans and computers. This format is intended to be standardized across all OpenPrintTag libraries and is defined in [opt_json.schema.json]({{repo}}/tree/main/utils/schema/opt_json.schema.json).
 {{ show_example("cat sample_data/sample_tag.bin | >rec_info.py --show-data --opt-check") }}
 
 ## Updating a tag

docs_src/sample_data/compact_data_to_fill.yaml

@@ -5,7 +5,7 @@ data:
     material_type: PLA
     brand_specific_material_id: 1
     tags: [glitter]
-    primary_color: [0x3D, 0x3E, 0x3D]
+    primary_color: "#3d3e3d"
     nominal_netto_full_weight: 1000
     transmission_distance: 0.2
     min_print_temperature: 205

docs_src/sample_data/data_to_fill.yaml

@@ -6,7 +6,7 @@ data:
     material_name: PLA Galaxy Black
     brand_specific_material_id: 1
     tags: [glitter]
-    primary_color: [0x3D, 0x3E, 0x3D]
+    primary_color: "#3d3e3d"
     manufactured_date: 1739371290
     nominal_netto_full_weight: 1000
     actual_netto_full_weight: 1012

requirements.txt

@@ -4,3 +4,5 @@ cbor2~=5.7.1
 jinja2~=3.1.5
 numpy~=2.2.3
 simple_parsing~=0.1.7
+referencing~=0.37.0
+jsonschema~=4.25.1

tests/encode_decode/01_info.yaml

@@ -8,7 +8,7 @@ regions:
     payload_offset: 4
     absolute_offset: 70
     size: 206
-    used_size: 148
+    used_size: 149
   aux:
     payload_offset: 210
     absolute_offset: 276
@@ -18,8 +18,8 @@ root:
   data_size: 312
   payload_size: 245
   overhead: 67
-  payload_used_size: 153
-  total_used_size: 220
+  payload_used_size: 154
+  total_used_size: 221
 data:
   meta:
     aux_region_offset: 210
@@ -34,8 +34,7 @@ data:
     nominal_netto_full_weight: 1000
     actual_netto_full_weight: 1012
     empty_container_weight: 280
-    primary_color:
-      hex: 3d3e3d
+    primary_color: '#3d3e3dff'
     tags:
     - glitter
     density: 1.24
@@ -57,9 +56,12 @@ data:
   aux: {}
 raw_data:
   meta: a10218d2
-  main: bf041b000007d0fcab45f9056a33333463353466303838080009000a76504c412050727573612047616c61787920426c61636b0b6950727573616d656e740e1a68d3c7d7101903e8111903f41219011813433d3e3d181c9f17ff181df93cf6182218cd182318e1182418aa182518281826183c18271218281828182914182a1840182b18c8182c1864182d183418389f0001ffff00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+  main: bf041b000007d0fcab45f9056a33333463353466303838080009000a76504c412050727573612047616c61787920426c61636b0b6950727573616d656e740e1a68d3c7d7101903e8111903f41219011813443d3e3dff181c9f17ff181df93cf6182218cd182318e1182418aa182518281826183c18271218281828182914182a1840182b18c8182c1864182d183418389f0001ffff000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
   aux: a000000000000000000000000000000000000000000000000000000000000000000000
 uri: https://3dtag.org/s/334c54f088
+validate:
+  warnings: []
+  errors: []
 opt_check:
   warnings: []
   errors: []

tests/encode_decode/01_input.yaml

@@ -8,8 +8,7 @@ data:
     material_type: PLA
     brand_name: Prusament
     material_name: PLA Prusa Galaxy Black
-    primary_color:
-      hex: 3D3E3D
+    primary_color: "#3d3e3dff"
     tags: [glitter]
     certifications: [ul_2818, ul_94_v0]
     density: 1.24

tests/encode_decode/02_info.yaml

@@ -34,8 +34,7 @@ data:
     nominal_netto_full_weight: 1000
     actual_netto_full_weight: 1050
     empty_container_weight: 280
-    primary_color:
-      hex: 24292a
+    primary_color: '#24292a'
     tags: []
     density: 1.27
     min_print_temperature: 240
@@ -56,6 +55,9 @@ raw_data:
   main: bf041b000007d0fcab465c056a37616232616362353039080009010a6e50455447204a657420426c61636b0b6950727573616d656e740e1a68c01ae7101903e81119041a12190118134324292a181c9fff181df93d14182218f01823190104182418aa182518461826185a1827121828183c18291823182a1840182b18c8182c1864182d1834ff0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
   aux: a000000000000000000000000000000000000000000000000000000000000000000000
 uri: https://3dtag.org/s/7ab2acb509
+validate:
+  warnings: []
+  errors: []
 opt_check:
   warnings: []
   errors: []

tests/encode_decode/02_input.yaml

@@ -7,8 +7,7 @@ data:
     material_type: PETG
     brand_name: Prusament
     material_name: PETG Jet Black
-    primary_color:
-      hex: 24292A
+    primary_color: "#24292a"
     tags: []
     density: 1.27
 

tests/encode_decode/03_info.yaml

@@ -33,8 +33,7 @@ data:
     nominal_netto_full_weight: 1000
     actual_netto_full_weight: 1050
     empty_container_weight: 280
-    primary_color:
-      hex: 24292a
+    primary_color: '#24292a'
     tags: []
     density: 1.27
     min_print_temperature: 240
@@ -58,6 +57,9 @@ uri: null
 opt_check:
   warnings:
   - Missing recommended field 'brand_name'
+  - Failed to deduce brand_uuid
+  - Failed to deduce material_uuid
+  - Failed to deduce package_uuid
   errors:
   - 'Fields preheat_temperature (300), min_print_temperature (240): a <= b'
   - 'Fields preheat_temperature (300), max_print_temperature (210): a <= b'
@@ -66,9 +68,6 @@ opt_check:
   - 'Fields min_chamber_temperature (90), max_chamber_temperature (60): a <= b'
   - 'Fields container_hole_diameter (210), container_inner_diameter (100): a <= b'
   - 'Fields container_hole_diameter (210), container_outer_diameter (200): a <= b'
-  - Failed to deduce brand_uuid
-  - Failed to deduce material_uuid
-  - Failed to deduce package_uuid
   notes: []
   uuids:
     brand_uuid: null

tests/encode_decode/03_input.yaml

@@ -1,13 +1,13 @@
 test_config:
   extra_required_fields: null
+  expect_success: false
 data:
   main:
     # Material information
     material_class: FFF
     material_type: PETG
     material_name: PETG Jet Black
-    primary_color:
-      hex: 24292A
+    primary_color: "#24292a"
     tags: []
     density: 1.27
 

tests/encode_decode/04_info.yaml

@@ -32,8 +32,7 @@ data:
     nominal_netto_full_weight: 750
     actual_netto_full_weight: 756
     empty_container_weight: 310
-    primary_color:
-      hex: '303030'
+    primary_color: '#303030'
     tags:
     - abrasive
     - contains_carbon_fiber
@@ -59,12 +58,15 @@ raw_data:
   main: bf080009150a7819436172626f6e582050454b4b2d412b4346313520426c61636b0b67334458546563680e1a690c5d9b101902ee111902f4121901361343303030181c9f04181f181eff181df93d8f1821f9366618221901681823190186182518781826188c1827183c1828188c1829185a182a183d182b18c6182c1864182d183518346750454b4b2d434618361a000372d0ff0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
   aux: a000000000000000000000000000000000000000000000000000000000000000000000
 uri: https://www.3dxtech.com/
-opt_check:
+validate:
   warnings:
   - Missing recommended field 'gtin'
   - Missing recommended field 'preheat_temperature'
-  errors:
+  errors: []
+opt_check:
+  warnings:
   - Failed to deduce package_uuid
+  errors: []
   notes: []
   uuids:
     brand_uuid: 0d616a90-9d18-567b-92f9-ce471171f898

tests/encode_decode/04_input.yaml

@@ -10,8 +10,7 @@ data:
     brand_name: 3DXTech
     material_name: CarbonX PEKK-A+CF15 Black
     material_abbreviation: PEKK-CF
-    primary_color:
-      hex: "303030"
+    primary_color: "#303030"
     tags: [abrasive, contains_carbon_fiber, contains_carbon]
     density: 1.39
 

tests/encode_decode/05_info.yaml

@@ -0,0 +1,69 @@
+regions:
+  meta:
+    payload_offset: 0
+    absolute_offset: 42
+    size: 4
+    used_size: 4
+  main:
+    payload_offset: 4
+    absolute_offset: 46
+    size: 230
+    used_size: 23
+  aux:
+    payload_offset: 234
+    absolute_offset: 276
+    size: 35
+    used_size: 1
+root:
+  data_size: 312
+  payload_size: 269
+  overhead: 43
+  payload_used_size: 28
+  total_used_size: 71
+data:
+  meta:
+    aux_region_offset: 234
+  main:
+    material_class: FFF
+    transmission_distance: 5.1
+  aux: {}
+unknown_fields:
+  main:
+    19ffff: '6474657374'
+raw_data:
+  meta: a10218ea
+  main: bf0800181bfb401466666666666619ffff6474657374ff000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+  aux: a000000000000000000000000000000000000000000000000000000000000000000000
+uri: null
+validate:
+  warnings:
+  - Region 'main' contains unknown fields
+  - Missing recommended field 'gtin'
+  - Missing recommended field 'material_type'
+  - Missing recommended field 'material_name'
+  - Missing recommended field 'brand_name'
+  - Missing recommended field 'manufactured_date'
+  - Missing recommended field 'nominal_netto_full_weight'
+  - Missing recommended field 'actual_netto_full_weight'
+  - Missing recommended field 'empty_container_weight'
+  - Missing recommended field 'primary_color'
+  - Missing recommended field 'tags'
+  - Missing recommended field 'density'
+  - Missing recommended field 'min_print_temperature'
+  - Missing recommended field 'max_print_temperature'
+  - Missing recommended field 'preheat_temperature'
+  - Missing recommended field 'min_bed_temperature'
+  - Missing recommended field 'max_bed_temperature'
+  errors: []
+opt_check:
+  warnings:
+  - Failed to deduce brand_uuid
+  - Failed to deduce material_uuid
+  - Failed to deduce package_uuid
+  errors: []
+  notes: []
+  uuids:
+    brand_uuid: null
+    material_uuid: null
+    package_uuid: null
+    instance_uuid: null

tests/encode_decode/05_input.yaml

@@ -0,0 +1,12 @@
+test_config:
+  extra_required_fields: null
+data:
+  main:
+    material_class: FFF
+unknown_fields:
+  main:
+    # 27 (= transmission distance): 5.1
+    "181b": "fb4014666666666666"
+
+    # 65535 (invalid value): "test"
+    "19ffff": "6474657374"

tests/run_tests.py

@@ -118,12 +118,15 @@ def check_util_output(name, data, compare_fn):
         if val := yml.get("tag_uid"):
             info_args += ["--tag-uid", val]
 
+        expect_success = yml.get("expect_success", True)
+
     utils_test(
         init_args=init_args,
         update_args=[str(file)],
         info_args=info_args,
         expected_info_fn=fn_info,
         expected_data_fn=f"{fn_base}_data.bin",
+        expect_success=expect_success,
     )
 
 

tests/specific/unknown_info_1.yaml

@@ -25,6 +25,9 @@ data:
     aux_region_offset: 234
   main: {}
   aux: {}
+unknown_fields:
+  main:
+    1926fd: 6d48656c6c6f2c20776f726c6421
 raw_data:
   meta: a10218ea
   main: bf1926fd6d48656c6c6f2c20776f726c6421ff00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000

tests/specific/unknown_info_2.yaml

@@ -26,6 +26,9 @@ data:
   main:
     material_class: FFF
   aux: {}
+unknown_fields:
+  main:
+    1926fd: 6d48656c6c6f2c20776f726c6421
 raw_data:
   meta: a10218ea
   main: bf08001926fd6d48656c6c6f2c20776f726c6421ff0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000

tests/validate/01.yaml

@@ -5,8 +5,7 @@ data:
     material_type: PLA
     brand_name: Prusament
     material_name: PLA Prusa Galaxy Black
-    primary_color:
-      hex: 3D3E3D
+    primary_color: "#3d3e3d"
     tags: [glitter]
     density: 1.24