Skip to content

ci: validate schema packs and examples; port the examples to v2 - #15

Merged
praveenjha527 merged 1 commit into
mainfrom
ci/validate-packs-and-examples
Nov 12, 2026
Merged

praveenjha527 merged 1 commit into
mainfrom
ci/validate-packs-and-examples

Conversation

@praveenjha527

Copy link
Copy Markdown
Contributor

Summary

Adds CI for this repository and makes every example payload valid.

Until now nothing checked the schema packs or the examples. The six typed objects in the hyperlocal guide did not validate against the packs, its messages did not match the core beckn.yaml shapes, and the courier, interstate, long-haul and express pages were still in the v1 message shape (search, order, fulfillment, tags).

What is added

tools/validate.py, run by .github/workflows/validate.yml on every pull request and on main.

python tools/validate.py packs checks, for every pack:

  • the five required files and the version directory name;
  • schema.json against the JSON Schema 2020-12 meta-schema;
  • every $ref resolving to a file and fragment inside this repository;
  • attributes.yaml and schema.json describing the same type, at every depth;
  • the title in both files matching the pack name;
  • README reference rows naming the same target as attributes.yaml;
  • an instance built from the schema's own examples being accepted, and an OpenAPI envelope being rejected;
  • the pack's context covering its properties and its vocab declaring its class;
  • every pair of pack contexts composing under JSON-LD 1.1 (they are protected, so a mismatch is an error for anyone combining two packs).

python tools/validate.py examples checks every JSON block under docs/example_implementations:

  • the envelope against core Context and the message against the core action schema, from beckn.yaml at protocol-specifications-v2@a22300a;
  • each typed logistics object against its pack;
  • properties the pack does not define. The packs leave objects open, so these passed silently before.

What changes in the docs

  • Hyperlocal implementation guide: all eight payloads rewritten so they pass. The narrative, topology and slot mapping are unchanged. Five sentences that described the old payload shapes are corrected, the host is now schema.nfh.global, and three open questions are added (the shape of Commitment.resources[].quantity, offer-level service terms, and what discovery filters evaluate against).
  • Courier, interstate, long haul, express: ported to v2 with discover, on_discover, on_confirm and on_status messages (express also has on_update and rate). Company names are replaced with example.net identifiers. Each page ends with a short list of what the packs cannot express yet.
  • Hyperlocal README: the v1 payloads are removed; the page now points to the guide, which covers the same use case.

Slot usage introduced by the ports

The guide's mapping is followed. Two placements are new and worth a look:

  • Consignment in commitments[].commitmentAttributes (courier, interstate, long haul).
  • Carrier in provider.providerAttributes at discovery.

Verification

  • packs: 26 packs, 0 problems. examples: 26 messages and 50 typed objects, 0 problems.
  • The checks fail when they should: a string in place of a number in an example, and a wrong title in a pack, are both reported.
  • On main before this change, examples reports 112 problems.

Not in this PR

  • docs/1_Overview.md to docs/3_Semantic_Relationships_With_Beckn.md, docs/Logistics_Ontology.md and docs/API-Flows.md still describe the older ontology and v1 flows. They are outside docs/example_implementations and are not validated yet.
  • The gaps listed on each example page are recorded, not fixed.

🤖 Generated with Claude Code

Add tools/validate.py and a workflow that runs it on every pull request:

- packs: required files, JSON Schema 2020-12 validity, every $ref
  resolving inside the repository, attributes.yaml and schema.json
  describing the same type, titles, README reference rows, an instance
  built from each schema's own examples, and pairwise composition of the
  protected JSON-LD contexts.
- examples: every JSON block under docs/example_implementations, the
  message against the core beckn.yaml action schema and each typed
  logistics object against its pack, including properties the pack does
  not define.

Rewrite the hyperlocal guide's payloads so they pass, and port the
courier, interstate, long-haul and express examples from the v1 message
shape to v2. Each page lists what the packs cannot express yet.

Co-Authored-By: Claude <noreply@anthropic.com>
@praveenjha527
praveenjha527 merged commit 3e03100 into main Nov 12, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant