@gruncellka/porto-data 0.3.1 → 0.4.1

package/porto_data/schemas/layouts.schema.json

@@ -0,0 +1,156 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/gruncellka/porto-data/refs/heads/main/porto_data/schemas/layouts.schema.json",
+  "title": "Envelope layouts by jurisdiction",
+  "description": "Print geometry on the envelope front per ISO 3166-1 alpha-2 jurisdiction. Physical sizes: formats/envelopes.json. Coordinates: origin top-left, mm, landscape front. Optional standard cites the norm (e.g. DIN678, SN010130, NFEN13850).",
+  "type": "object",
+  "required": [
+    "file_type",
+    "unit",
+    "jurisdictions"
+  ],
+  "definitions": {
+    "rectangleMm": {
+      "type": "object",
+      "required": [
+        "x",
+        "y",
+        "width",
+        "height"
+      ],
+      "properties": {
+        "x": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "y": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "width": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "height": {
+          "type": "integer",
+          "minimum": 1
+        }
+      },
+      "additionalProperties": false
+    },
+    "postMarkAnchorMm": {
+      "type": "object",
+      "required": [
+        "x",
+        "y"
+      ],
+      "properties": {
+        "x": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "y": {
+          "type": "integer",
+          "minimum": 0
+        }
+      },
+      "additionalProperties": false
+    },
+    "layoutBody": {
+      "type": "object",
+      "required": [
+        "post_mark",
+        "window"
+      ],
+      "properties": {
+        "post_mark": {
+          "$ref": "#/definitions/postMarkAnchorMm"
+        },
+        "window": {
+          "type": "object",
+          "required": [
+            "supported"
+          ],
+          "properties": {
+            "supported": {
+              "type": "boolean"
+            },
+            "area": {
+              "$ref": "#/definitions/rectangleMm"
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "envelopeLayoutRow": {
+      "type": "object",
+      "required": [
+        "orientation",
+        "layout"
+      ],
+      "properties": {
+        "standard": {
+          "type": "string",
+          "minLength": 1
+        },
+        "orientation": {
+          "type": "string",
+          "enum": [
+            "landscape",
+            "portrait"
+          ]
+        },
+        "layout": {
+          "$ref": "#/definitions/layoutBody"
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "format": "uri"
+    },
+    "file_type": {
+      "type": "string",
+      "const": "layouts"
+    },
+    "unit": {
+      "type": "object",
+      "required": [
+        "dimension"
+      ],
+      "properties": {
+        "dimension": {
+          "type": "string",
+          "const": "mm"
+        }
+      },
+      "additionalProperties": false
+    },
+    "jurisdictions": {
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": {
+        "type": "object",
+        "required": [
+          "envelopes"
+        ],
+        "properties": {
+          "envelopes": {
+            "type": "object",
+            "minProperties": 1,
+            "additionalProperties": {
+              "$ref": "#/definitions/envelopeLayoutRow"
+            }
+          }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/porto_data/schemas/limits.schema.json

@@ -0,0 +1,253 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/gruncellka/porto-data/refs/heads/main/porto_data/schemas/limits.schema.json",
+  "title": "Provider limits schema",
+  "description": "Provider-scoped operational limits: how this operator applies service (conflicts, infrastructure, internal policy). Not shared legal sanctions—those live in policy/restrictions.json (country / EU / UN regimes, independent of any single carrier). Each limits file is keyed by provider; regime periods and calendar use the provider operational timezone (see frameworks.timezone, aligned with providers.json for the same provider id).",
+  "type": "object",
+  "required": [
+    "file_type",
+    "provider",
+    "unit",
+    "limits",
+    "frameworks"
+  ],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "format": "uri",
+      "description": "JSON Schema URI reference"
+    },
+    "file_type": {
+      "type": "string",
+      "const": "limits",
+      "description": "File type identifier"
+    },
+    "provider": {
+      "type": "string",
+      "pattern": "^[a-z_]+$",
+      "description": "Provider id (must match path providers/<id>/)"
+    },
+    "unit": {
+      "type": "object",
+      "required": [
+        "country_code",
+        "date"
+      ],
+      "properties": {
+        "country_code": {
+          "type": "string",
+          "const": "ISO 3166-1 alpha-2"
+        },
+        "date": {
+          "type": "string",
+          "const": "ISO 8601"
+        }
+      },
+      "additionalProperties": false
+    },
+    "limits": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "country_code",
+          "status",
+          "reason",
+          "notes",
+          "effective_from"
+        ],
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "country_code": {
+            "type": "string",
+            "pattern": "^[A-Z]{2}$"
+          },
+          "region_code": {
+            "type": "string"
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "restricted",
+              "limited",
+              "prohibited",
+              "severe",
+              "operational"
+            ]
+          },
+          "reason": {
+            "type": "string"
+          },
+          "description": {
+            "type": "string"
+          },
+          "notes": {
+            "type": "string"
+          },
+          "areas": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string"
+            }
+          },
+          "entity_type": {
+            "type": "string",
+            "enum": [
+              "country",
+              "territory",
+              "disputed"
+            ]
+          },
+          "effective_from": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "format": "date"
+          },
+          "effective_to": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "format": "date"
+          },
+          "partial": {
+            "type": "boolean"
+          },
+          "reference": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "format": "uri"
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "context": {
+      "type": "object",
+      "description": "Provider-facing narrative only (this limits file’s carrier). Do not use this object to stand in for legal regimes; policy/restrictions.json holds verifiable destination rows and EU/UN-style frameworks.",
+      "properties": {
+        "national": {
+          "type": "object",
+          "required": [
+            "description",
+            "notes"
+          ],
+          "properties": {
+            "description": {
+              "type": "string"
+            },
+            "notes": {
+              "type": "string"
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "frameworks": {
+      "type": "object",
+      "description": "Operational regime metadata for this provider. Each framework documents the regime time window (effective_from / effective_to, nullable) interpreted in timezone (provider operational calendar—must match providers.<id>.timezone). limits[] row effective_from/effective_to remain authoritative for SDK activation; framework dates are the documented span, usually aligned with the primary limit row.",
+      "patternProperties": {
+        "^[A-Z0-9_]+$": {
+          "type": "object",
+          "required": [
+            "id",
+            "label",
+            "description",
+            "type",
+            "applies_to",
+            "effective_from",
+            "effective_to",
+            "timezone"
+          ],
+          "properties": {
+            "id": {
+              "type": "string"
+            },
+            "label": {
+              "type": "string"
+            },
+            "description": {
+              "type": "string"
+            },
+            "type": {
+              "type": "string",
+              "enum": [
+                "conflict",
+                "infrastructure",
+                "political"
+              ]
+            },
+            "applies_to": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "pattern": "^[A-Z]{2}$|^ALL$"
+              }
+            },
+            "regions": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "required": [
+                  "code",
+                  "name"
+                ],
+                "properties": {
+                  "code": {
+                    "type": "string"
+                  },
+                  "name": {
+                    "type": "string"
+                  }
+                },
+                "additionalProperties": false
+              }
+            },
+            "note": {
+              "type": "string"
+            },
+            "reference": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "format": "uri"
+            },
+            "effective_from": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "format": "date"
+            },
+            "effective_to": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "format": "date"
+            },
+            "timezone": {
+              "type": "string",
+              "minLength": 3,
+              "pattern": "^[A-Za-z0-9_+-]+(/[A-Za-z0-9_+-]+)+$",
+              "description": "IANA zone for this provider’s operational calendar (must match providers.json → providers.<id>.timezone for the limits file’s provider). Used when interpreting framework and limits row effective_* dates."
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}

package/porto_data/schemas/mappings.schema.json

@@ -0,0 +1,73 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/gruncellka/porto-data/refs/heads/main/porto_data/schemas/mappings.schema.json",
+  "title": "Porto-data schema ↔ data mappings",
+  "description": "Maps each JSON Schema path under schemas/ to its canonical data file (policy/, formats/, providers/<id>/, or bundle root). Blocks mirror bundle layout: policy, formats, registry (e.g. providers.json), providers. Provider keys must match providers.json.",
+  "type": "object",
+  "required": [
+    "mappings"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "format": "uri"
+    },
+    "mappings": {
+      "type": "object",
+      "required": [
+        "policy",
+        "formats",
+        "registry",
+        "providers"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "policy": {
+          "type": "object",
+          "minProperties": 0,
+          "additionalProperties": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "^(?!\\.\\./)([A-Za-z0-9_.-]+/)*[A-Za-z0-9_.-]+\\.json$"
+          },
+          "description": "Schema paths → data under policy/."
+        },
+        "formats": {
+          "type": "object",
+          "minProperties": 0,
+          "additionalProperties": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "^(?!\\.\\./)([A-Za-z0-9_.-]+/)*[A-Za-z0-9_.-]+\\.json$"
+          },
+          "description": "Schema paths → data under formats/."
+        },
+        "registry": {
+          "type": "object",
+          "minProperties": 0,
+          "additionalProperties": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "^(?!\\.\\./)([A-Za-z0-9_.-]+/)*[A-Za-z0-9_.-]+\\.json$"
+          },
+          "description": "Schema paths → bundle-root manifest files (e.g. providers.json)."
+        },
+        "providers": {
+          "type": "object",
+          "minProperties": 0,
+          "additionalProperties": {
+            "type": "object",
+            "minProperties": 1,
+            "additionalProperties": {
+              "type": "string",
+              "minLength": 1,
+              "pattern": "^(?!\\.\\./)([A-Za-z0-9_.-]+/)*[A-Za-z0-9_.-]+\\.json$"
+            }
+          },
+          "description": "Provider id → map of schema path → data path under providers/<id>/."
+        }
+      }
+    }
+  }
+}

package/porto_data/schemas/markets.schema.json

@@ -0,0 +1,186 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/gruncellka/porto-data/refs/heads/main/porto_data/schemas/markets.schema.json",
+  "title": "Markets (country fiscal and calendar policy)",
+  "description": "Per-country currency, VAT, international quote currencies, and postal working-day calendar. providers.json country resolves fiscal and working_days defaults via markets[COUNTRY]. All operators in the same country share one market row.",
+  "type": "object",
+  "required": [
+    "file_type",
+    "unit",
+    "markets"
+  ],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "format": "uri"
+    },
+    "file_type": {
+      "type": "string",
+      "const": "markets"
+    },
+    "description": {
+      "type": "string"
+    },
+    "unit": {
+      "type": "object",
+      "description": "Encoding hints for country_code and currency fields in this file.",
+      "required": [
+        "country_code",
+        "currency"
+      ],
+      "properties": {
+        "country_code": {
+          "type": "string",
+          "const": "ISO 3166-1 alpha-2"
+        },
+        "currency": {
+          "type": "string",
+          "const": "ISO 4217"
+        }
+      },
+      "additionalProperties": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "markets": {
+      "type": "object",
+      "minProperties": 1,
+      "patternProperties": {
+        "^[A-Z]{2}$": {
+          "$ref": "#/definitions/market"
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "definitions": {
+    "currency_code": {
+      "type": "string",
+      "enum": [
+        "EUR",
+        "CHF",
+        "UAH",
+        "USD"
+      ]
+    },
+    "vat_lane": {
+      "type": "object",
+      "required": [
+        "inclusive"
+      ],
+      "properties": {
+        "inclusive": {
+          "type": "boolean",
+          "description": "When true, published tariff amounts for this lane include VAT."
+        }
+      },
+      "additionalProperties": false
+    },
+    "vat": {
+      "type": "object",
+      "properties": {
+        "rate": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "description": "Standard VAT rate as a fraction (e.g. 0.2 for 20%)."
+        },
+        "exempt": {
+          "type": "boolean",
+          "description": "When true, universal letter service is VAT-exempt in this market (all lanes)."
+        },
+        "domestic": {
+          "$ref": "#/definitions/vat_lane",
+          "description": "VAT presentation for domestic-zone tariff rows."
+        },
+        "international": {
+          "$ref": "#/definitions/vat_lane",
+          "description": "VAT presentation for international-zone tariff rows."
+        }
+      },
+      "additionalProperties": false
+    },
+    "settlement": {
+      "type": "object",
+      "required": [
+        "currency",
+        "fx",
+        "fx_date"
+      ],
+      "properties": {
+        "currency": {
+          "$ref": "#/definitions/currency_code",
+          "description": "Currency charged at checkout or service date."
+        },
+        "fx": {
+          "type": "string",
+          "minLength": 1,
+          "description": "FX rate source when quoted amount differs from settlement currency (e.g. NBU)."
+        },
+        "fx_date": {
+          "type": "string",
+          "minLength": 1,
+          "description": "When FX applies (e.g. service for service-date rate)."
+        }
+      },
+      "additionalProperties": false
+    },
+    "working_days": {
+      "type": "object",
+      "required": [
+        "weekdays",
+        "exclude_public_holidays"
+      ],
+      "properties": {
+        "weekdays": {
+          "type": "string",
+          "enum": [
+            "mon_fri",
+            "mon_sat"
+          ],
+          "description": "Which weekdays count toward operator-stated delivery SLAs in this market."
+        },
+        "exclude_public_holidays": {
+          "type": "boolean",
+          "description": "When true, public holidays of this market do not count as delivery days."
+        }
+      },
+      "additionalProperties": false
+    },
+    "market": {
+      "type": "object",
+      "required": [
+        "currency",
+        "working_days"
+      ],
+      "properties": {
+        "currency": {
+          "$ref": "#/definitions/currency_code",
+          "description": "Default domestic postal quote currency for this market."
+        },
+        "working_days": {
+          "$ref": "#/definitions/working_days",
+          "description": "Default postal working-day calendar for operator delivery SLAs in this market."
+        },
+        "international_currency": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "$ref": "#/definitions/currency_code"
+          },
+          "description": "Allowed row-level quote currencies when a tariff row differs from currency."
+        },
+        "vat": {
+          "$ref": "#/definitions/vat"
+        },
+        "settlement": {
+          "$ref": "#/definitions/settlement"
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}