Proposal: org.Package for shipped packages (UBL cac:Package)

[samlown]

Proposal for a structured org.Package model, following the discussion in #859 about multi-box shipments and the removal of the packaging+* attribute keys.

Stacked on #859 (items-en16931-proposal) since it reuses org.Attribute for package details.

Design

org.Package is based on the UBL cac:Package class, where packages are first-class objects with their own dimension list rather than prefixed attributes on the item:

• key — type of package (box, pallet, crate, …) instead of a raw code. Each pre-defined key maps to its UN/ECE Recommendation 21 code via cbc.Definition.Map (unece-rec21), with Package.UNECERec21() resolving the code for converters (extended keys like box+gift resolve via their base; unknown keys fall back to ZZ mutually defined). Keys must be based on one of the pre-defined keys, mirroring pay.HasValidMeansKey.
• count — number of identical packages of this type.
• identities — package-level identifiers such as a GS1 SSCC (≈ UBL cbc:ID).
• attributes — reuses org.Attribute with bare keys (length, weight, …), context supplying the referent; duplicate keys rejected (≈ UBL cac:MeasurementDimension, whose AttributeID/Measure+unitCode maps to our type/amount+unit).
• Attached as bill.Line.Packages, following UBL/Peppol which hang packages off despatch lines; most useful in bill.Delivery documents but available on any line.

The ES delivery example (examples/es/delivery.yaml) shows the intended usage: 10 mugs shipped as 2 boxes of 3.5 kg each.

Open questions

• Placement: line-level (Line.Packages, as proposed) vs restricting to delivery documents only, vs also/instead on org.Item for stable "ships as N boxes" catalogue data.
• count semantics: number of identical packages (proposed) vs UBL's cbc:Quantity (item units contained in the package) — or both.
• Nesting: UBL supports recursive ContainedPackage (boxes on a pallet); omitted here for simplicity.
• Key list: initial 20 keys aligned with existing org.Unit presentation unit names where they overlap; tray maps to DS to match UnitTray's XDS.

Pre-Review Checklist

• Opened this PR as a draft
• Read the CONTRIBUTING.md guide.
• Performed a self-review of my code.
• Added thorough tests with at least 90% code coverage.
• Modified or created example GOBL documents to show my changes in use, if appropriate.
• Added links to the source of the changes in tax regimes or addons, either structured or in the comments.
• Run go generate . to ensure that the Schemas and Regime data are up to date.
• Reviewed and fixed all linter warnings.
• Been obsessive with pointer nil checks to avoid panics.
• Updated the CHANGELOG.md with an overview of my changes.
• Marked this PR as ready for review.

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 96.92308% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 94.75%. Comparing base (9250e46) to head (f45bbf5).
⚠️ Report is 9 commits behind head on items-en16931-proposal.

Files with missing lines	Patch %	Lines
org/package.go	96.72%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@                    Coverage Diff                     @@
##           items-en16931-proposal     #897      +/-   ##
==========================================================
+ Coverage                   94.74%   94.75%   +0.01%     
==========================================================
  Files                         317      318       +1     
  Lines                       17269    17334      +65     
==========================================================
+ Hits                        16361    16425      +64     
  Misses                        561      561              
- Partials                      347      348       +1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.