@gruncellka/porto-data 0.3.0 → 0.4.1

package/porto_data/schemas/products.schema.json

@@ -1,122 +1,350 @@
 {
-    "$schema": "http://json-schema.org/draft-07/schema#",
-    "$id": "https://raw.githubusercontent.com/gruncellka/porto-data/refs/heads/main/porto_data/schemas/products.schema.json",
-    "title": "Products Schema",
-    "description": "Schema for postal products definitions",
-    "type": "object",
-    "required": [
-        "file_type",
-        "unit",
-        "products"
-    ],
-    "properties": {
-        "$schema": {
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/gruncellka/porto-data/refs/heads/main/porto_data/schemas/products.schema.json",
+  "title": "Products Schema",
+  "description": "Schema for postal products definitions",
+  "type": "object",
+  "required": [
+    "file_type",
+    "provider",
+    "unit",
+    "products"
+  ],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "format": "uri",
+      "description": "JSON Schema URI reference"
+    },
+    "file_type": {
+      "type": "string",
+      "const": "products",
+      "description": "File type identifier"
+    },
+    "provider": {
+      "type": "string",
+      "pattern": "^[a-z_]+$",
+      "description": "Provider identifier (e.g. deutschepost, ukrposhta, laposte, swisspost)"
+    },
+    "unit": {
+      "type": "object",
+      "description": "Product-level units: weight only. Envelope formats: envelope_ids reference formats/envelopes.json; print layout via formats/layouts.json by jurisdiction.",
+      "required": [
+        "weight"
+      ],
+      "properties": {
+        "weight": {
+          "type": "string",
+          "const": "g"
+        }
+      },
+      "additionalProperties": false
+    },
+    "products": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "porto_id",
+          "name",
+          "envelope_ids",
+          "zones",
+          "effective_from",
+          "effective_to",
+          "mark_type",
+          "tracking_mode",
+          "delivery"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-z_]+$",
+            "description": "Semantic English product ID"
+          },
+          "name": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Official product name (original language)"
+          },
+          "native_id": {
+            "description": "Carrier API product identifier for this row (contract catalog / ordering). Not the bundle `id` and not unified `porto_id`. Examples: DHL Internetmarke REST `productCode` (integer). Values must match the operator’s live catalog (e.g. `/app/catalog` contract products).",
+            "oneOf": [
+              {
+                "type": "integer",
+                "minimum": 1
+              },
+              {
+                "type": "string",
+                "minLength": 1
+              }
+            ]
+          },
+          "porto_id": {
+            "$ref": "porto_ids.schema.json#/definitions/product_porto_id",
+            "description": "Unified Porto letter size bucket (small … extra_large). Not service semantics — use services.json for registered/tracking add-ons. Graph and prices use native `id`, not `porto_id`."
+          },
+          "envelope_ids": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "string",
+              "enum": [
+                "C8",
+                "C7",
+                "C6",
+                "DL",
+                "C5",
+                "B6",
+                "B5",
+                "C4",
+                "C3",
+                "B4"
+              ]
+            },
+            "description": "Supported envelope format ids (global envelopes.json)"
+          },
+          "zones": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "string",
+              "pattern": "^[a-z0-9_]+$"
+            },
+            "description": "Zones where this product is available (must align with graph.edges.products for this product_id)"
+          },
+          "weight_tier": {
             "type": "string",
-            "format": "uri",
-            "description": "JSON Schema URI reference"
+            "pattern": "^W[0-9]+$",
+            "description": "Optional single weight tier id when the product maps to one step; full matrix is graph.edges + weights + prices."
+          },
+          "effective_from": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "format": "date",
+            "description": "Catalog baseline for this product row (e.g. 2026-01-01); not a claim about carrier real-world introduction."
+          },
+          "effective_to": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "format": "date",
+            "description": "Null while modeled; set when the product row is retired in the bundle."
+          },
+          "mark_type": {
+            "type": "string",
+            "enum": [
+              "stamp",
+              "label"
+            ],
+            "description": "What kind of provider mark this product produces when executed (data-driven; not inferred in adapters)."
+          },
+          "tracking_mode": {
+            "type": "string",
+            "enum": [
+              "none",
+              "optional",
+              "included"
+            ],
+            "description": "Whether tracking is expected on the execution result; actual tracking numbers are runtime-only (PortoMark), never stored in porto-data."
+          },
+          "delivery": {
+            "type": "array",
+            "minItems": 1,
+            "description": "Operator-stated delivery SLA per zone group. Union of all entry zones must equal product.zones exactly.",
+            "items": {
+              "$ref": "#/definitions/delivery_entry"
+            }
+          },
+          "included_features": {
+            "type": "array",
+            "uniqueItems": true,
+            "items": {
+              "type": "string",
+              "pattern": "^[a-z_]+$"
+            },
+            "description": "Provider feature ids bundled in base postage (see features.json). Optional add-ons remain in services.json."
+          },
+          "indemnity": {
+            "$ref": "#/definitions/indemnity",
+            "description": "Operator-stated loss/damage indemnity cap when the product tier defines one."
+          }
+        },
+        "additionalProperties": false,
+        "allOf": [
+          {
+            "if": {
+              "properties": {
+                "mark_type": {
+                  "const": "label"
+                }
+              },
+              "required": [
+                "mark_type"
+              ]
+            },
+            "then": {
+              "properties": {
+                "tracking_mode": {
+                  "enum": [
+                    "optional",
+                    "included"
+                  ]
+                }
+              }
+            }
+          }
+        ]
+      }
+    }
+  },
+  "definitions": {
+    "indemnity_max": {
+      "type": "object",
+      "required": [
+        "amount"
+      ],
+      "properties": {
+        "amount": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Indemnification cap in provider market minor units (markets[country].currency)."
+        }
+      },
+      "additionalProperties": false
+    },
+    "indemnity": {
+      "type": "object",
+      "required": [
+        "tier",
+        "max"
+      ],
+      "properties": {
+        "tier": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Operator-native indemnity"
         },
-        "file_type": {
+        "max": {
+          "$ref": "#/definitions/indemnity_max",
+          "description": "Maximum indemnification in case of loss or damage per operator tariff."
+        }
+      },
+      "additionalProperties": false
+    },
+    "delivery_entry": {
+      "type": "object",
+      "required": [
+        "zones",
+        "span",
+        "days_max"
+      ],
+      "properties": {
+        "zones": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
             "type": "string",
-            "const": "products",
-            "description": "File type identifier"
+            "pattern": "^[a-z0-9_]+$"
+          },
+          "description": "Zone ids from this product's zones[]; each product zone must appear in exactly one delivery entry."
         },
-        "unit": {
-            "type": "object",
+        "span": {
+          "type": "string",
+          "enum": [
+            "next",
+            "within",
+            "between"
+          ],
+          "description": "How to read days_max: next (exactly 1 day), within (up to days_max), between (days_min..days_max)."
+        },
+        "days_max": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Maximum counted delivery days for this zone group per operator tariff wording."
+        },
+        "days_min": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Minimum counted delivery days when span is between."
+        },
+        "weekdays": {
+          "type": "string",
+          "enum": [
+            "mon_fri",
+            "mon_sat"
+          ],
+          "description": "Optional override when operator text narrows or widens weekdays vs markets[country].working_days."
+        }
+      },
+      "additionalProperties": false,
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "span": {
+                "const": "next"
+              }
+            },
             "required": [
-                "dimension",
-                "weight"
-            ],
+              "span"
+            ]
+          },
+          "then": {
             "properties": {
-                "dimension": {
-                    "type": "string",
-                    "const": "mm"
-                },
-                "weight": {
-                    "type": "string",
-                    "const": "g"
-                }
+              "days_max": {
+                "const": 1
+              }
             },
-            "additionalProperties": false
+            "not": {
+              "required": [
+                "days_min"
+              ]
+            }
+          }
         },
-        "products": {
-            "type": "array",
-            "minItems": 1,
-            "items": {
-                "type": "object",
-                "required": [
-                    "id",
-                    "name",
-                    "dimension_ids",
-                    "supported_zones",
-                    "weight_tier",
-                    "effective_from",
-                    "effective_to"
-                ],
-                "properties": {
-                    "id": {
-                        "type": "string",
-                        "pattern": "^[a-z_]+$",
-                        "description": "Semantic English product ID"
-                    },
-                    "name": {
-                        "type": "string",
-                        "minLength": 1,
-                        "description": "Official German product name"
-                    },
-                    "dimension_ids": {
-                        "type": "array",
-                        "minItems": 1,
-                        "items": {
-                            "type": "string",
-                            "enum": [
-                                "DL",
-                                "C6",
-                                "C5",
-                                "C4",
-                                "B4"
-                            ]
-                        },
-                        "description": "Supported dimension IDs"
-                    },
-                    "supported_zones": {
-                        "type": "array",
-                        "minItems": 1,
-                        "items": {
-                            "type": "string",
-                            "enum": [
-                                "domestic",
-                                "zone_1_eu",
-                                "zone_2_europe",
-                                "world"
-                            ]
-                        },
-                        "description": "Zones where this product is available"
-                    },
-                    "weight_tier": {
-                        "type": "string",
-                        "pattern": "^W[0-9]+$",
-                        "description": "Weight tier ID"
-                    },
-                    "effective_from": {
-                        "type": [
-                            "string",
-                            "null"
-                        ],
-                        "format": "date",
-                        "description": "Product effective start date"
-                    },
-                    "effective_to": {
-                        "type": [
-                            "string",
-                            "null"
-                        ],
-                        "format": "date",
-                        "description": "Product effective end date"
-                    }
-                },
-                "additionalProperties": false
+        {
+          "if": {
+            "properties": {
+              "span": {
+                "const": "within"
+              }
+            },
+            "required": [
+              "span"
+            ]
+          },
+          "then": {
+            "not": {
+              "required": [
+                "days_min"
+              ]
             }
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "span": {
+                "const": "between"
+              }
+            },
+            "required": [
+              "span"
+            ]
+          },
+          "then": {
+            "required": [
+              "days_min"
+            ]
+          }
         }
-    },
-    "additionalProperties": false
+      ]
+    }
+  },
+  "additionalProperties": false
 }

package/porto_data/schemas/providers.schema.json

@@ -0,0 +1,71 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/gruncellka/porto-data/refs/heads/main/porto_data/schemas/providers.schema.json",
+  "title": "Provider registry",
+  "description": "Domain registry for postal providers. Folder providers/<id>/ is implementation storage only; authoritative ids and coarse metadata live here. IANA timezone: policy/jurisdictions.json → jurisdictions[country].timezone. Currency and VAT: policy/markets.json → markets[country]. Product-level mark_type and tracking_mode remain the execution source of truth.",
+  "type": "object",
+  "required": [
+    "providers"
+  ],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "format": "uri"
+    },
+    "providers": {
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": {
+        "type": "object",
+        "required": [
+          "label",
+          "name",
+          "country",
+          "mark_types"
+        ],
+        "properties": {
+          "label": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Short display name (UI / prose)"
+          },
+          "name": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Registered legal entity name"
+          },
+          "country": {
+            "type": "string",
+            "pattern": "^[A-Z]{2}$",
+            "description": "Primary country (ISO 3166-1 alpha-2). Timezone: policy/jurisdictions.json jurisdictions[this code].timezone. Currency and VAT: policy/markets.json markets[this code]."
+          },
+          "mark_types": {
+            "type": "array",
+            "minItems": 1,
+            "uniqueItems": true,
+            "items": {
+              "type": "string",
+              "enum": [
+                "stamp",
+                "label"
+              ]
+            },
+            "description": "Coarse overview; exact execution comes from each product"
+          },
+          "tracking_model": {
+            "type": "string",
+            "enum": [
+              "mixed",
+              "included",
+              "none",
+              "optional"
+            ],
+            "description": "Optional coarse provider-level tracking posture; products define tracking_mode precisely."
+          }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}