# beckn/schemas architecture

> Architecture diagram of the GitHub repository beckn/schemas, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/beckn/schemas
- Repository: https://github.com/beckn/schemas

## Overview

#### 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`.

Main entry points: [`schema/README.md`](https://github.com/beckn/schemas/blob/main/schema/README.md) (Versioned schema packages), [`schema/Contract/v2.0/attributes.yaml`](https://github.com/beckn/schemas/blob/main/schema/Contract/v2.0/attributes.yaml) (Contract & invoice), [`schema/context.jsonld`](https://github.com/beckn/schemas/blob/main/schema/context.jsonld) (Aggregate JSON-LD context), [`schema/Catalog/v2.2/attributes.yaml`](https://github.com/beckn/schemas/blob/main/schema/Catalog/v2.2/attributes.yaml) (Catalog)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_semantic["Semantic foundation"]
  node_readme["Repository entry points<br/>documentation<br/>[README.md]"]
  node_root_context["Aggregate JSON-LD context<br/>[context.jsonld]"]
  node_root_vocab["Aggregate RDF vocabulary<br/>[vocab.jsonld]"]
  node_package_model["Versioned schema packages<br/>[README.md]"]
end

subgraph group_lifecycle["Transaction schemas"]
  node_discover_catalog["Discovery &amp; catalog<br/>transaction schemas<br/>[attributes.yaml]"]
  node_selection_commitment["Selection &amp; commitment<br/>transaction schemas<br/>[attributes.yaml]"]
  node_confirmation_status["Confirmation &amp; status<br/>transaction schemas<br/>[attributes.yaml]"]
end

subgraph group_commerce["Commerce &amp; fulfillment"]
  node_catalog["Catalog<br/>core schema<br/>[attributes.yaml]"]
  node_supply["Provider, item &amp; offer<br/>core schemas<br/>[attributes.yaml]"]
  node_pricing["Price &amp; payment terms<br/>commercial schemas<br/>[attributes.yaml]"]
  node_contract_invoice["Contract &amp; invoice<br/>commercial schemas<br/>[attributes.yaml]"]
  node_fulfillment["Fulfillment &amp; tracking<br/>delivery schemas<br/>[attributes.yaml]"]
end

subgraph group_extensions["Shared &amp; sector extensions"]
  node_shared_types["Identity, location &amp; time<br/>shared schemas<br/>[attributes.yaml]"]
  node_package_context["Per-schema JSON-LD context<br/>[context.jsonld]"]
  node_sector_profiles["Sector profiles &amp; renderers<br/>extension metadata<br/>[profile.json]"]
end

subgraph group_maintenance["Authoring &amp; maintenance"]
  node_structure_docs["Schema lifecycle docs<br/>documentation"]
  node_governance["Contribution governance<br/>[CONTRIBUTING.md]"]
  node_context_generator{{"Context generator<br/>Python maintenance tool"}}
  node_vocab_generator{{"Vocabulary generator<br/>Python maintenance tool"}}
  node_parity_audit{{"Schema parity audit<br/>Python maintenance tool"}}
end

node_readme -->|"introduces"| node_package_model
node_structure_docs -->|"defines"| node_package_model
node_governance -->|"governs changes to"| node_structure_docs
node_package_model -->|"contains"| node_package_context
node_package_context -->|"aggregates into"| node_root_context
node_package_model -->|"contributes terms to"| node_root_vocab
node_context_generator -.->|"generates or audits"| node_root_context
node_vocab_generator -.->|"generates or audits"| node_root_vocab
node_parity_audit -.->|"checks parity"| node_package_model
node_discover_catalog -->|"exchanges"| node_catalog
node_catalog -->|"lists"| node_supply
node_selection_commitment -->|"selects"| node_supply
node_selection_commitment -->|"initiates"| node_contract_invoice
node_confirmation_status -->|"confirms or updates"| node_contract_invoice
node_contract_invoice -->|"uses"| node_pricing
node_contract_invoice -->|"requires"| node_fulfillment
node_confirmation_status -->|"reports status for"| node_fulfillment
node_shared_types -.->|"supports"| node_catalog
node_shared_types -.->|"supports"| node_contract_invoice
node_sector_profiles -->|"extends"| node_package_model
node_root_context -->|"resolves terms against"| node_root_vocab

click node_readme "https://github.com/beckn/schemas/blob/main/README.md"
click node_root_context "https://github.com/beckn/schemas/blob/main/schema/context.jsonld"
click node_root_vocab "https://github.com/beckn/schemas/blob/main/schema/vocab.jsonld"
click node_package_model "https://github.com/beckn/schemas/blob/main/schema/README.md"
click node_discover_catalog "https://github.com/beckn/schemas/blob/main/schema/DiscoverAction/v2.0/attributes.yaml"
click node_selection_commitment "https://github.com/beckn/schemas/blob/main/schema/SelectAction/v2.0/attributes.yaml"
click node_confirmation_status "https://github.com/beckn/schemas/blob/main/schema/ConfirmAction/v2.0/attributes.yaml"
click node_catalog "https://github.com/beckn/schemas/blob/main/schema/Catalog/v2.2/attributes.yaml"
click node_supply "https://github.com/beckn/schemas/blob/main/schema/Provider/v2.1/attributes.yaml"
click node_pricing "https://github.com/beckn/schemas/blob/main/schema/PriceSpecification/v2.2/attributes.yaml"
click node_contract_invoice "https://github.com/beckn/schemas/blob/main/schema/Contract/v2.0/attributes.yaml"
click node_fulfillment "https://github.com/beckn/schemas/blob/main/schema/Fulfillment/v2.1/attributes.yaml"
click node_shared_types "https://github.com/beckn/schemas/blob/main/schema/Organization/v2.0/attributes.yaml"
click node_package_context "https://github.com/beckn/schemas/blob/main/schema/Address/v2.0/context.jsonld"
click node_sector_profiles "https://github.com/beckn/schemas/blob/main/schema/ServiceOffer/v2.1/profile.json"
click node_structure_docs "https://github.com/beckn/schemas/blob/main/docs/2_Schema_Structure.md"
click node_governance "https://github.com/beckn/schemas/blob/main/CONTRIBUTING.md"
click node_context_generator "https://github.com/beckn/schemas/blob/main/tools/generate-context-jsonld.py"
click node_vocab_generator "https://github.com/beckn/schemas/blob/main/tools/generate-vocab-jsonld.py"
click node_parity_audit "https://github.com/beckn/schemas/blob/main/tools/schema_parity_audit.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_readme,node_root_context,node_root_vocab,node_package_model toneBlue
class node_discover_catalog,node_selection_commitment,node_confirmation_status toneAmber
class node_catalog,node_supply,node_pricing,node_contract_invoice,node_fulfillment toneMint
class node_shared_types,node_package_context,node_sector_profiles toneRose
class node_structure_docs,node_governance,node_context_generator,node_vocab_generator,node_parity_audit toneIndigo
```

## Components

### Semantic foundation

- [Repository entry points](https://github.com/beckn/schemas/blob/main/README.md): documentation · `README.md`
- [Aggregate JSON-LD context](https://github.com/beckn/schemas/blob/main/schema/context.jsonld): JSON-LD context · Maps shared terms to the Beckn namespace. · `schema/context.jsonld`
- [Aggregate RDF vocabulary](https://github.com/beckn/schemas/blob/main/schema/vocab.jsonld): RDF vocabulary · Defines the shared class and property surface. · `schema/vocab.jsonld`
- [Versioned schema packages](https://github.com/beckn/schemas/blob/main/schema/README.md): schema package · Each concept has independently released structural and semantic artifacts. · `schema/README.md`

### Transaction schemas

Data definitions for Beckn interaction stages.

- [Discovery & catalog](https://github.com/beckn/schemas/blob/main/schema/DiscoverAction/v2.0/attributes.yaml): transaction schemas · `schema/DiscoverAction/v2.0/attributes.yaml`
- [Selection & commitment](https://github.com/beckn/schemas/blob/main/schema/SelectAction/v2.0/attributes.yaml): transaction schemas · `schema/SelectAction/v2.0/attributes.yaml`
- [Confirmation & status](https://github.com/beckn/schemas/blob/main/schema/ConfirmAction/v2.0/attributes.yaml): transaction schemas · `schema/ConfirmAction/v2.0/attributes.yaml`

### Commerce & fulfillment

- [Catalog](https://github.com/beckn/schemas/blob/main/schema/Catalog/v2.2/attributes.yaml): core schema · `schema/Catalog/v2.2/attributes.yaml`
- [Provider, item & offer](https://github.com/beckn/schemas/blob/main/schema/Provider/v2.1/attributes.yaml): core schemas · `schema/Provider/v2.1/attributes.yaml`
- [Price & payment terms](https://github.com/beckn/schemas/blob/main/schema/PriceSpecification/v2.2/attributes.yaml): commercial schemas · `schema/PriceSpecification/v2.2/attributes.yaml`
- [Contract & invoice](https://github.com/beckn/schemas/blob/main/schema/Contract/v2.0/attributes.yaml): commercial schemas · `schema/Contract/v2.0/attributes.yaml`
- [Fulfillment & tracking](https://github.com/beckn/schemas/blob/main/schema/Fulfillment/v2.1/attributes.yaml): delivery schemas · `schema/Fulfillment/v2.1/attributes.yaml`

### Shared & sector extensions

- [Identity, location & time](https://github.com/beckn/schemas/blob/main/schema/Organization/v2.0/attributes.yaml): shared schemas · Cross-domain dependencies for transaction and commerce graphs. · `schema/Organization/v2.0/attributes.yaml`
- [Per-schema JSON-LD context](https://github.com/beckn/schemas/blob/main/schema/Address/v2.0/context.jsonld): JSON-LD context · Isolates semantic terms for an individual schema release. · `schema/Address/v2.0/context.jsonld`
- [Sector profiles & renderers](https://github.com/beckn/schemas/blob/main/schema/ServiceOffer/v2.1/profile.json): extension metadata · Profiles, renderers, and examples support specialized vertical schemas. · `schema/ServiceOffer/v2.1/profile.json`

### Authoring & maintenance

- [Schema lifecycle docs](https://github.com/beckn/schemas/blob/main/docs/2_Schema_Structure.md): documentation · Normative structure, JSON-LD, versioning, and deprecation guidance. · `docs/2_Schema_Structure.md`
- [Contribution governance](https://github.com/beckn/schemas/blob/main/CONTRIBUTING.md): governance · `CONTRIBUTING.md`
- [Context generator](https://github.com/beckn/schemas/blob/main/tools/generate-context-jsonld.py): Python maintenance tool · `tools/generate-context-jsonld.py`
- [Vocabulary generator](https://github.com/beckn/schemas/blob/main/tools/generate-vocab-jsonld.py): Python maintenance tool · `tools/generate-vocab-jsonld.py`
- [Schema parity audit](https://github.com/beckn/schemas/blob/main/tools/schema_parity_audit.py): Python maintenance tool · `tools/schema_parity_audit.py`

## Connections

- Repository entry points → Versioned schema packages: introduces
- Schema lifecycle docs → Versioned schema packages: defines
- Contribution governance → Schema lifecycle docs: governs changes to
- Versioned schema packages → Per-schema JSON-LD context: contains
- Per-schema JSON-LD context → Aggregate JSON-LD context: aggregates into
- Versioned schema packages → Aggregate RDF vocabulary: contributes terms to
- Context generator → Aggregate JSON-LD context: generates or audits
- Vocabulary generator → Aggregate RDF vocabulary: generates or audits
- Schema parity audit → Versioned schema packages: checks parity
- Discovery & catalog → Catalog: exchanges
- Catalog → Provider, item & offer: lists
- Selection & commitment → Provider, item & offer: selects
- Selection & commitment → Contract & invoice: initiates
- Confirmation & status → Contract & invoice: confirms or updates
- Contract & invoice → Price & payment terms: uses
- Contract & invoice → Fulfillment & tracking: requires
- Confirmation & status → Fulfillment & tracking: reports status for
- Identity, location & time → Catalog: supports
- Identity, location & time → Contract & invoice: supports
- Sector profiles & renderers → Versioned schema packages: extends
- Aggregate JSON-LD context → Aggregate RDF vocabulary: resolves terms against