beckn/schemas

Purpose and boundaries

This is the Beckn Protocol Tier 2 core-schema repository: a versioned, domain-agnostic library of JSON-LD/RDF terms and structural schema definitions. It is not an executable service or web application. Tier 1 protocol transport/envelopes live externally; Tier 3 domain packs extend these core types.

Entry points: README.md, schema/README.md, and the root semantic artifacts schema/context.jsonld and schema/vocab.jsonld.

Schema-package model

Each concept is independently versioned under schema/{SchemaName}/vX.Y/. A package generally contains:

• attributes.yaml: structural attributes/schema source;

• context.jsonld: JSON-LD term mappings;

• vocab.jsonld: RDF class/property vocabulary;

• optional schema.json, profile.json, renderer.json, or examples.

Examples: schema/Catalog/v2.2/attributes.yaml, schema/Item/v2.1/schema.json, schema/GroceryItem/v2.0/profile.json.

Semantic contract layer

The root context and vocabulary provide the shared beckn namespace and aggregate semantic surface used by implementations and downstream domain extensions. Per-schema artifacts isolate each type’s semantic definition while allowing independent releases.

Key boundary: ordinary JSON consumers can use payloads structurally, while JSON-LD/RDF consumers resolve terms into globally unique identifiers and graph relationships. Paths: schema/context.jsonld, schema/vocab.jsonld, schema/Address/v2.0/context.jsonld.

Transaction lifecycle schema families

The repository models Beckn interaction stages as data/action types rather than runtime handlers:

• discovery and catalog exchange: schema/DiscoverAction/v2.0/attributes.yaml, schema/Catalog/v2.2/attributes.yaml, schema/Offer/v2.1/attributes.yaml;

• selection, initialization, and commitment: schema/SelectAction/v2.0/attributes.yaml, schema/InitAction/v2.0/attributes.yaml, schema/Contract/v2.0/attributes.yaml;

• confirmation, updates, cancellation, and status callbacks: schema/ConfirmAction/v2.0/attributes.yaml, schema/UpdateAction/v2.0/attributes.yaml, schema/OnStatusAction/v2.0/attributes.yaml.

Tier 1 API messages are expected to reference these payload definitions; this repository does not define request routing or transport behavior.

Core commerce and fulfillment graph

Catalogs connect providers, items, offers, pricing, contracts/orders, and fulfillment. These types form the reusable graph that verticals specialize:

• supply: schema/Provider/v2.1/attributes.yaml, schema/Item/v2.1/attributes.yaml, schema/Offer/v2.1/attributes.yaml;

• commercial terms: schema/PriceSpecification/v2.2/attributes.yaml, schema/PaymentTerms/v2.0/attributes.yaml, schema/Invoice/v2.2/attributes.yaml;

• delivery/tracking: schema/Fulfillment/v2.1/attributes.yaml, schema/Tracking/v2.1/attributes.yaml, schema/TrackAction/v2.1/attributes.yaml.

Cross-domain and sector extensions

Common identity, location, time, descriptor, policy, and error types are shared dependencies across all transaction graphs: schema/Organization/v2.0/attributes.yaml, schema/Location/v2.0/attributes.yaml, schema/TimePeriod/v2.1/attributes.yaml.

The repository also contains richer mobility, logistics, hiring, education, and retail-oriented schemas. Some v2.1 packages include rendering/profile metadata, indicating a more presentation- or profile-driven extension surface: schema/ServiceOffer/v2.1/profile.json, schema/HiringJobOffer/v2.1/renderer.json, schema/HomeAndKitchenItem/v2.0/examples/home-kitchen-item.json.

Authoring, versioning, and automation

Documentation defines the normative structure, JSON-LD vocabulary practices, and schema lifecycle: docs/2_Schema_Structure.md, docs/3_JSON_LD_Context_and_Vocabulary.md, docs/4_Versioning_and_Deprecation.md. Governance controls change acceptance: CONTRIBUTING.md, GOVERNANCE.md.

Python utilities generate or audit aggregate context/vocabulary consistency and schema parity; they are repository-maintenance tooling, not production runtime infrastructure: tools/generate-context-jsonld.py, tools/generate-vocab-jsonld.py, tools/schema_parity_audit.py.