Skip to content

docs(readme): state the identifier schemes and refresh the schema table - #327

Merged
LKSNDRTMLKV merged 2 commits into
mainfrom
docs/readme-identifier-and-gates
Sep 21, 2026
Merged

LKSNDRTMLKV merged 2 commits into
mainfrom
docs/readme-identifier-and-gates

Conversation

@LKSNDRTMLKV

Copy link
Copy Markdown
Member

Top of the stack: #322 → #325 → #326 → this. Retarget to main as the parents merge.

🚨 The schema table was stale in every row

#295 bumped every product groups schema and the README table was not updated.
Battery read v2.0.0 – v2.6.0 (actually v2.7.0), electronics – v1.2.0
(v1.4.0), textile and furniture – v1.2.0 (v1.3.0), and the five-group row
– v1.1.0 (v1.2.0). Every row wrong.

Corrected, and a line added pointing at product-groups/*.json as the real
home — this table is hand-maintained and has now been behind twice.

New: the identifier is not a GTIN

A section under Key Features covering the three EN 18219 clause 5 schemes,
because the interesting part is not the mechanism but who it lets in:
requiring a GTIN is requiring GS1 membership. Schemes 2 and 3 are
self-issuing, and modelling only scheme 1 quietly excludes every manufacturer
without a Company Identification Number.

It also states the distinction that caused a live defect: a carrier is not an
identifier
. A Digital Link happens to contain a GTIN; a scheme 2 or 3 carrier
does not, and reading one out of the other is how an internal UUID ends up
submitted to a public authority.

New: how to write a plugins validate_input

The plugins section now shows require_product_identifier and says plainly not
to reach for require_gtin, which reads a flat top-level key that product group
data no longer carries.

The same change goes into crates/dpp-plugin-sdk/README.md, where it replaces a
todo!() placeholder — and that one is doctested, so the example compiles on
every run and cannot drift from the API the way the schema table did. Verified:
cargo test --doc -p dpp-plugin-sdk passes.

Verification

just check green, 1561/1561, plugins formatted and linted, bans ok, licenses ok, sources ok.

@LKSNDRTMLKV LKSNDRTMLKV added type/defect Something published or encoded here is wrong or unbackable now urgency/backlog Owed, unscheduled surface/docs-only Contained to documentation; no code depends on it labels Sep 19, 2026
@LKSNDRTMLKV
LKSNDRTMLKV force-pushed the chore/ci-parity-with-the-engine branch from 0e513d6 to 250b09a Compare September 21, 2026 15:43
Base automatically changed from chore/ci-parity-with-the-engine to main September 21, 2026 15:46
@LKSNDRTMLKV
LKSNDRTMLKV force-pushed the docs/readme-identifier-and-gates branch from 9f74c46 to e0ac387 Compare September 21, 2026 15:55
@LKSNDRTMLKV

Copy link
Copy Markdown
Member Author

Rebased onto main (#322, #325 and #326 have all landed; delta conserved exactly).

Verified the table rather than trusting it — every one of the twelve rows matches what crates/dpp-domain/schemas/*/ actually ships, including the two easy ones to get wrong: battery's v1.0.0 → v2.0.0 gap (there is no v1.1.0) and the twelve-group count. The SDK README example compiles under cargo test --doc, which is the part that keeps it from drifting the way the table did.

One line added: just check in the README's quick-start block still read fmt + clippy + test + doctests + plugins + doc + audit, and check has since gained plugin-gates-self-test (#325) and lock-check (#326). It now names the lockfile gate. This is the same hand-maintained-summary drift the schema table just demonstrated, one block further down the same file.

just check green, 1564/1564, 3 lockfiles match their manifests., bans ok, licenses ok, sources ok.

@LKSNDRTMLKV
LKSNDRTMLKV merged commit 64eda3b into main Sep 21, 2026
11 checks passed
@LKSNDRTMLKV
LKSNDRTMLKV deleted the docs/readme-identifier-and-gates branch September 21, 2026 15:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

surface/docs-only Contained to documentation; no code depends on it type/defect Something published or encoded here is wrong or unbackable now urgency/backlog Owed, unscheduled

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant