@gruncellka/porto-data 0.3.0 → 0.4.1

package/porto_data/schemas/marks.schema.json

@@ -0,0 +1,127 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/gruncellka/porto-data/refs/heads/main/porto_data/schemas/marks.schema.json",
+  "title": "Provider mark profiles",
+  "description": "Per-provider catalog of mark geometry and payload type. Profile size (width × height) is nominal footprint in mm. Resolution paths live in graph.json edges.marks.",
+  "type": "object",
+  "required": [
+    "file_type",
+    "provider",
+    "default_profile",
+    "profiles"
+  ],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "format": "uri",
+      "description": "JSON Schema URI reference"
+    },
+    "file_type": {
+      "type": "string",
+      "const": "marks",
+      "description": "File type identifier"
+    },
+    "provider": {
+      "type": "string",
+      "pattern": "^[a-z_]+$",
+      "description": "Provider id (must match path providers/<id>/)"
+    },
+    "unit": {
+      "type": "object",
+      "required": [
+        "dimension"
+      ],
+      "properties": {
+        "dimension": {
+          "type": "string",
+          "const": "mm",
+          "description": "Intrinsic size and layout coordinates use millimetres"
+        }
+      },
+      "additionalProperties": false
+    },
+    "default_profile": {
+      "type": "string",
+      "pattern": "^[a-z0-9_]+$",
+      "description": "Fallback profile id when graph.edges.marks has no entry for a zone"
+    },
+    "profiles": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "mark_type",
+          "label"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-z0-9_]+$",
+            "description": "Stable profile id; referenced from graph.edges.marks"
+          },
+          "mark_type": {
+            "type": "string",
+            "enum": [
+              "stamp",
+              "label"
+            ],
+            "description": "Must match product.mark_type for products using this profile"
+          },
+          "label": {
+            "type": "string",
+            "minLength": 1,
+            "description": "English short name for tooling"
+          },
+          "description": {
+            "type": "string",
+            "minLength": 1,
+            "description": "When to use this profile vs others"
+          },
+          "scope_notes": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Optional: domestic vs international, registered, channel notes"
+          },
+          "size": {
+            "type": "object",
+            "description": "Nominal width × height of the franking graphic in file unit.dimension (mm); optional until verified from API/spec",
+            "required": [
+              "width",
+              "height"
+            ],
+            "properties": {
+              "width": {
+                "type": "integer",
+                "minimum": 1
+              },
+              "height": {
+                "type": "integer",
+                "minimum": 1
+              }
+            },
+            "additionalProperties": false
+          },
+          "mime_type": {
+            "type": "array",
+            "minItems": 1,
+            "uniqueItems": true,
+            "items": {
+              "type": "string",
+              "enum": [
+                "image/png",
+                "image/jpeg",
+                "application/pdf",
+                "application/octet-stream"
+              ]
+            },
+            "description": "IANA media types the provider API may return for this profile; order is not significant"
+          }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/porto_data/schemas/metadata.schema.json

@@ -0,0 +1,183 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/gruncellka/porto-data/refs/heads/main/porto_data/schemas/metadata.schema.json",
+  "title": "Porto-data bundle metadata",
+  "description": "Generated checksum manifest for schemas and data files (see scripts/generate_metadata.py). The bundle section records mappings.json and providers.json (plus schemas) explicitly.",
+  "type": "object",
+  "required": [
+    "$schema",
+    "project",
+    "generated_at",
+    "policy",
+    "formats",
+    "registry",
+    "providers",
+    "checksums"
+  ],
+  "additionalProperties": false,
+  "definitions": {
+    "fileInfo": {
+      "type": "object",
+      "required": [
+        "path",
+        "checksum",
+        "size"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "path": {
+          "type": "string",
+          "minLength": 1
+        },
+        "checksum": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{64}$"
+        },
+        "size": {
+          "type": "integer",
+          "minimum": 0
+        }
+      }
+    },
+    "schemaInfo": {
+      "type": "object",
+      "required": [
+        "path",
+        "checksum",
+        "size",
+        "url"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "path": {
+          "type": "string",
+          "minLength": 1
+        },
+        "checksum": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{64}$"
+        },
+        "size": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "url": {
+          "type": "string",
+          "description": "Schema $id URL when present; empty string if unavailable."
+        }
+      }
+    },
+    "entityBundle": {
+      "type": "object",
+      "required": [
+        "data",
+        "schema"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "data": {
+          "$ref": "#/definitions/fileInfo"
+        },
+        "schema": {
+          "$ref": "#/definitions/schemaInfo"
+        }
+      }
+    }
+  },
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "format": "uri"
+    },
+    "project": {
+      "type": "object",
+      "required": [
+        "name",
+        "version",
+        "description"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1
+        },
+        "version": {
+          "type": "string",
+          "minLength": 1
+        },
+        "description": {
+          "type": "string"
+        }
+      }
+    },
+    "generated_at": {
+      "type": "string",
+      "minLength": 1,
+      "description": "ISO 8601 instant (UTC, Z suffix from generator)."
+    },
+    "policy": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/definitions/entityBundle"
+      }
+    },
+    "formats": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/definitions/entityBundle"
+      }
+    },
+    "registry": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/definitions/entityBundle"
+      }
+    },
+    "providers": {
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": {
+        "type": "object",
+        "minProperties": 1,
+        "additionalProperties": {
+          "$ref": "#/definitions/entityBundle"
+        }
+      }
+    },
+    "bundle": {
+      "type": "object",
+      "description": "Root manifest files: mappings (layout) and providers registry, each with data + schema checksums.",
+      "required": [
+        "mappings",
+        "providers_registry"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "mappings": {
+          "$ref": "#/definitions/entityBundle"
+        },
+        "providers_registry": {
+          "$ref": "#/definitions/entityBundle"
+        }
+      }
+    },
+    "checksums": {
+      "type": "object",
+      "required": [
+        "algorithm",
+        "note"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "algorithm": {
+          "type": "string",
+          "const": "SHA-256"
+        },
+        "note": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}

package/porto_data/schemas/porto_ids.schema.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/gruncellka/porto-data/refs/heads/main/porto_data/schemas/porto_ids.schema.json",
+  "title": "Porto ID vocabulary",
+  "description": "Canonical porto_id enums for cross-provider SDK normalization. Normative list: docs/id.md. Disjointness: product_porto_id (size buckets) must not overlap service_porto_id or feature_porto_id; service and feature may share tokens where capability and priced add-on align (see id.md). Do not add values without semver-major review.",
+  "definitions": {
+    "product_porto_id": {
+      "type": "string",
+      "enum": [
+        "small",
+        "medium",
+        "large",
+        "extra_large",
+        "postcard"
+      ],
+      "description": "Letter size bucket for SDK product input only (no service semantics: registered, tracking, return_receipt, … belong on services/features)"
+    },
+    "service_porto_id": {
+      "type": "string",
+      "enum": [
+        "registered",
+        "registered_return_receipt",
+        "tracking",
+        "insurance",
+        "return_receipt",
+        "thickness",
+        "proof_of_mailing",
+        "proof_of_delivery"
+      ],
+      "description": "Unified add-on service bucket for SDK input"
+    },
+    "feature_porto_id": {
+      "type": "string",
+      "enum": [
+        "tracking_number",
+        "proof_of_mailing",
+        "recipient_signature",
+        "return_receipt",
+        "proof_of_delivery",
+        "thickness_surcharge"
+      ],
+      "description": "Unified capability feature bucket for cross-operator semantics"
+    }
+  }
+}

package/porto_data/schemas/product_prices.schema.json

@@ -0,0 +1,126 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/gruncellka/porto-data/refs/heads/main/porto_data/schemas/product_prices.schema.json",
+  "title": "Product postage prices",
+  "description": "Base letter/postage grid: product_id × zone × weight_tier. Amounts in cents. Convention: price[].effective_from uses the catalog baseline date (currently 2026-01-01) as bundle snapshot start, not carrier historical introduction dates.",
+  "type": "object",
+  "required": [
+    "file_type",
+    "provider",
+    "unit",
+    "product_prices"
+  ],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "format": "uri"
+    },
+    "file_type": {
+      "type": "string",
+      "const": "product_prices"
+    },
+    "provider": {
+      "type": "string",
+      "pattern": "^[a-z_]+$",
+      "description": "Provider identifier"
+    },
+    "unit": {
+      "type": "object",
+      "required": [
+        "price",
+        "currency"
+      ],
+      "properties": {
+        "price": {
+          "type": "string",
+          "const": "cents"
+        },
+        "currency": {
+          "type": "string",
+          "enum": [
+            "EUR",
+            "CHF",
+            "UAH",
+            "USD"
+          ],
+          "description": "Default currency for rows in this file. Set row.currency only when a row is quoted in another currency (must differ from this default)."
+        }
+      },
+      "additionalProperties": false
+    },
+    "product_prices": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": [
+          "product_id",
+          "zone",
+          "weight_tier",
+          "price"
+        ],
+        "properties": {
+          "product_id": {
+            "type": "string",
+            "pattern": "^[a-z_]+$",
+            "description": "Must match products.json id"
+          },
+          "zone": {
+            "type": "string",
+            "pattern": "^[a-z0-9_]+$"
+          },
+          "weight_tier": {
+            "type": "string",
+            "pattern": "^W[0-9]+$"
+          },
+          "currency": {
+            "type": "string",
+            "enum": [
+              "EUR",
+              "CHF",
+              "UAH",
+              "USD"
+            ],
+            "description": "Row override when this amount is not in unit.currency. Omit when same as file default. SDK priority: row → file unit → markets[country].currency."
+          },
+          "price": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "object",
+              "required": [
+                "amount",
+                "effective_from"
+              ],
+              "properties": {
+                "amount": {
+                  "type": "integer",
+                  "minimum": 0
+                },
+                "effective_from": {
+                  "type": [
+                    "string",
+                    "null"
+                  ],
+                  "format": "date",
+                  "description": "Row valid from this date (ISO 8601). Provider bundles use the catalog baseline (e.g. 2026-01-01) unless superseding rows exist."
+                },
+                "effective_to": {
+                  "type": [
+                    "string",
+                    "null"
+                  ],
+                  "format": "date",
+                  "description": "Null while current; set when a newer price row replaces this amount."
+                }
+              },
+              "additionalProperties": false
+            }
+          }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}