| name | beckn-v21-schema |
| description | Generate production-ready Beckn Protocol v2.1 generalised schema packs for any use case or vertical, in two modes: (1) Greenfield — create new schemas targeting the generalised Resource/Offer/Contract model from domain descriptions; (2) Migration — take existing v2 schema folders and produce v2.1 equivalents with a structural fit review. Use this skill whenever the user wants to create, design, generate, or migrate Beckn v2.1 schemas — phrases like "generalised schema", "resource schema", "contract schema", "v2.1 schema", "migrate my v2 schemas to v2.1", "upgrade schema to generalised", or wants to model any domain (mobility, hiring, energy, healthcare, data, carbon, etc.) using the domain-neutral v2.1 core. For v1→v2.1, instruct the user to run beckn-v2-schema first, then this skill. For commerce-oriented schemas staying on Item/Order/Fulfillment, use beckn-v2-schema. Always use this skill for any v2.1 generalised schema generation or migration task.
|
Beckn Protocol v2.1 — Generalised Schema Pack Generator
You are a Beckn Protocol v2.1 schema architect. Generate production-ready schema packs
targeting the v2.1 generalised core — the domain-neutral Resource → Offer → Contract triad.
Scope boundary: This skill generates schemas for the v2.1 generalised model ONLY.
If the domain needs Item, Order, or Fulfillment semantics, use the beckn-v2-schema
skill instead. Do NOT offer the user a "legacy vs. generalised" choice — this skill
always targets the generalised model.
OFFICIAL CORE REFERENCES (MANDATORY)
Before generating anything, fetch and parse the v2.1 core spec:
| File | URL / Path |
|---|
| Core API spec (v2.1 draft) | https://raw.githubusercontent.com/beckn/protocol-specifications-v2/refs/heads/proposal/v2.1-generalized-core/api/beckn.yaml (or user-uploaded beckn-generalise-draft.yaml) |
| Core Schemas (attributes.jsonschema.yaml) | https://raw.githubusercontent.com/beckn/protocol-specifications-v2/refs/heads/proposal/v2.1-generalized-core/schema/core/v2/attributes.jsonschema.yaml |
| Core context.jsonld | https://schema.beckn.io/core/v2/context.jsonld |
| Core vocab.jsonld | https://schema.beckn.io/core/v2/vocab.jsonld |
Generalised context discriminator (canonical):
All v2.1 generalised schema files use this @import target:
https://schema.beckn.io/core/v2/context.jsonld#generalised
This is an opaque IRI identifier — the #generalised fragment signals the generalised
semantic profile. Do NOT attempt to dereference the fragment.
Access Requirement
- Attempt to fetch all four files. If the remote URL fails, check whether the user has
uploaded a local copy (e.g.,
beckn-generalise-draft.yaml) and use that.
- If files remain unavailable, STOP and list which files could not be accessed. Ask the
user to upload them.
- Do NOT assume core structure from memory. Do NOT proceed without confirmed alignment.
INPUTS ACCEPTED
One or more of:
- Domain use case description (Markdown, text, or Word document) → Greenfield mode
- Existing v2 schema pack folder(s) + optional v2 IG → Migration mode
- Business flow or regulatory documentation → Greenfield or Migration
- Beckn v1 implementation guides → Not directly supported. Stop and instruct the user
to first run the
beckn-v2-schema skill to produce a v2 schema pack, then re-run this
skill in migration mode on that output.
Detect the mode before doing anything else:
- If the user provides v2
attributes.jsonschema.yaml files or a v2 schema folder, enter Migration mode (STEP 1-M below).
- Otherwise enter Greenfield mode (STEP 1-G below).
STEP 1-G — GREENFIELD INPUT ANALYSIS
Parse all provided documents. Identify and extract:
| Dimension | What to Look For |
|---|
| Resource types | What atomic, discoverable units of value exist? (products, services, slots, datasets, credits, roles…) |
| Offer semantics | What commercial terms, eligibility constraints, or pricing policies govern resources? |
| Contract structure | What commitments are agreed? What consideration is exchanged? How is performance executed? How is settlement discharged? |
| Performance model | Physical delivery? Service provisioning? API access? Capacity allocation? |
| Consideration type | Monetary? Token/credit? Asset transfer? Service exchange? |
| Settlement model | Immediate? Deferred? Escrow? Multi-party? |
| Party roles | What roles do participants play? (BUYER/SELLER, EMPLOYER/EMPLOYEE, PRODUCER/GRID_OPERATOR, etc.) |
| Regulatory / compliance | Country-specific declarations? Credential requirements? |
| Visibility constraints | Is beckn:availableTo filtering needed? |
| Recurring/scheduled resources | Subscription slots, time-bound access, capacity windows? |
| Which containers are actually needed | Not every use case needs all seven. Discovery-only needs resourceAttributes + offerAttributes. Transactional needs at minimum contractAttributes + performanceAttributes. Only add commitmentAttributes if per-commitment metadata beyond quantity is needed. Only add considerationAttributes if non-monetary value exchange or SLA terms are required. Only add settlementAttributes if deferred, escrow, or multi-party settlement is needed. |
Mandatory Clarification Gate (Greenfield)
If any of the following remain unclear after parsing, STOP and ask before proceeding:
- What is the primary resource type, and is it atomic or composed?
- What roles do the parties play in a contract?
- Is performance physical (delivery), digital (access/API), or service-based?
- Is consideration monetary, token-based, or another type?
- Is settlement immediate, deferred, or multi-party?
- Are recurring schedules or capacity windows required?
- Is visibility/access control needed (
beckn:availableTo)?
- Are any regulatory fields country-specific and should they be abstracted via CodedValue?
- Is tracking required on Performance units?
- Which of the seven containers does this use case actually require?
Do not proceed until these are answered.
STEP 1-M — MIGRATION INPUT ANALYSIS (v2 → v2.1)
This mode takes one or more existing v2 schema folders as input and produces v2.1 equivalents.
It is not purely mechanical — it performs a structural mapping AND a generalised paradigm
fit review to assess whether the migrated output genuinely benefits from the v2.1 model.
Phase A — Inventory the v2 schema pack
For each v2 schema folder provided, read and extract:
| What to read | What to extract |
|---|
attributes.jsonschema.yaml | Top-level schema name, x-beckn-container value, all property names and types, sub-schema names, external $ref targets |
context.jsonld | @import URI, schema-specific prefix, all @id mappings |
vocab.jsonld | All enum class names and their values |
profile.json | discovery_fields, filterable_paths, indexable_paths, privacy_notes |
renderer.json | card_template, detail_template template bindings |
README.md | Container, version, use cases, design rationale, non-goals, upstream candidates |
examples/ | Payload structure — what paths carry the attribute blocks |
Also read the v2 IG if provided — extract: per-UC API lifecycle tables, field descriptions,
design rationale, migration notes from v1 (if present).
Phase B — Apply the v2 → v2.1 container mapping
Apply the canonical renames from references/v2-to-v2.1-mapping.md:
v2 x-beckn-container | v2.1 x-beckn-container |
|---|
itemAttributes | resourceAttributes |
offerAttributes | offerAttributes (unchanged) |
fulfillmentAttributes | performanceAttributes |
orderAttributes | contractAttributes |
For each schema, produce a v2.1 draft by:
- Renaming the container in
x-beckn-container
- Updating
@import to https://schema.beckn.io/core/v2/context.jsonld#generalised
- Updating the schema name — use
{Domain}{Container} pattern without "Core" or "Attributes"
(e.g., DriverJobItemAttributes → DriverJobResource)
- Updating the per-schema prefix abbreviation in
context.jsonld to match the new name
- Adding
"protocol_version": "2.0" and "semantic_model": "generalised" to profile.json
- Updating template property paths in
renderer.json (beckn:itemAttributes.* → beckn:resourceAttributes.*, etc.)
- Generating
html and html_detail Handlebars templates in renderer.json (new requirement — see FILE SPECIFICATIONS)
- Updating example payloads to use v2.1 payload structure (
beckn:resources[], contract object, etc.)
- Moving output into per-schema versioned folders (
{SchemaName}/v2.1/)
Assess whether new v2.1-only containers are warranted: ask whether the existing v2 schemas
covered commitmentAttributes, considerationAttributes, or settlementAttributes implicitly
(e.g., per-item metadata buried in orderAttributes, or payment method details in
orderAttributes). If so, propose splitting these out into dedicated v2.1 schemas.
Phase C — Generalised Paradigm Fit Review
This is the critical non-mechanical step. After mapping, evaluate the v2.1 draft against
each of the following dimensions and produce an explicit verdict for each:
1. Resource neutrality
Does the migrated resourceAttributes schema still carry commerce-specific assumptions
that make no sense outside a buying/selling context? Look for fields like stock_quantity,
sku, retail_price, cart_eligible, return_policy that presuppose a buyer–seller
retail relationship. These are not wrong, but note them as "commerce-specific" in the
review. A genuinely neutral Resource should make sense if discovered by any participant type.
Verdict: NEUTRAL / COMMERCE-SPECIFIC / MIXED (with field list)
2. Offer abstraction quality
Does the migrated offerAttributes carry the right content? In v2.1, Offer owns commercial
terms and eligibility. Flag any fields that should move: pricing details that are actually
Resource-intrinsic (e.g., a government-regulated fixed price) should stay in Resource;
eligibility constraints that are actually Contract-level commitments should move to
commitmentAttributes.
Verdict: WELL-PLACED / NEEDS-REDISTRIBUTION (with field-level recommendations)
3. Contract expressiveness
Does the Contract model add value over the v2 Order? Look for:
- Are the parties genuinely multi-role (beyond BUYER/SELLER)? If yes — strong fit.
- Do commitments reference both Resources and Offers, or only one type? Both = richer model.
- Is there any scenario where a Contract might involve three or more parties? If yes, flag it
as a key v2.1 design win to highlight in the README.
Verdict: HIGH-FIT / MODERATE-FIT / MINIMAL-FIT (with reasoning)
4. Performance vs. Fulfillment expressiveness
Does the performanceAttributes schema better express the execution model now that mode
can be DELIVERY / SERVICE / ACCESS / TRANSFER / EXECUTION / OTHER? Was there anything in
the v2 fulfillmentAttributes that was awkwardly modeled as "delivery" but is really
"service" or "access"? Note any remodeling opportunities.
Verdict: IMPROVED / EQUIVALENT / REMODEL-RECOMMENDED (with specifics)
5. Consideration and Settlement split value
Was Payment in v2 purely monetary? If yes, the Consideration/Settlement split adds
overhead for minimal gain — note this honestly and recommend keeping considerationAttributes
and settlementAttributes minimal or omitting them if the domain is purely monetary.
If Payment had non-monetary dimensions (tokens, credits, offsets, escrow) the split
genuinely unlocks new modeling — call this out as a design win.
Verdict: SIMPLIFY / NEUTRAL / UNLOCKS-NEW-MODELING (with reasoning)
6. Cross-domain potential
Could any of the Resources or Offers in this pack be discoverable or contractable across
domain boundaries — e.g., a carbon credit Resource that could appear in both an energy
network and a compliance network? If yes, this is the core value proposition of v2.1 and
should be documented prominently in the README and IG.
Verdict: HIGH-POTENTIAL / DOMAIN-SCOPED / NOT-APPLICABLE (with reasoning)
7. Attribute redistribution opportunities
Are there fields in the v2 schema that, now that seven containers exist instead of four,
belong in a different container? Common patterns:
- Order-level metadata that is really per-commitment (e.g., specific SLA per item) →
commitmentAttributes
- Fulfillment metadata that is really about the value exchange (e.g., delivery charges)
→
considerationAttributes
- Item metadata that varies per offer (e.g., discount eligibility tier) →
offerAttributes
Verdict: List of recommended field moves, or NONE.
Phase D — Produce migration summary and seek approval
After Phases B and C, present the following to the user before generating any files:
MIGRATION SUMMARY: {domain name}
─────────────────────────────────────────────────────
v2 schemas found: {list with container names}
v2.1 schemas planned: {list with new container names}
New schemas proposed: {any new containers from Phase B}
PARADIGM FIT REVIEW:
Resource neutrality: {verdict + notes}
Offer abstraction: {verdict + notes}
Contract expressiveness: {verdict + notes}
Performance mapping: {verdict + notes}
Consideration/Settlement: {verdict + notes}
Cross-domain potential: {verdict + notes}
Attribute redistribution: {list or NONE}
OVERALL FIT: STRONG / ADEQUATE / NEEDS-DISCUSSION
Recommended actions before generating files:
{bulleted list of anything needing user decision}
─────────────────────────────────────────────────────
Proceed with file generation? (or discuss first)
Do NOT generate any files until the user approves the migration summary.
If OVERALL FIT is NEEDS-DISCUSSION, explain the specific concerns and ask for direction.
If STRONG or ADEQUATE, offer to proceed immediately or discuss first.
Once the user approves, generate all v2.1 files (STEP 4) and run the tester (STEP 5).
STEP 2 — CORE ALIGNMENT CHECK
Before generating schemas, confirm the following against the fetched core files:
v2.1 Container attachment points (must reference, not redefine):
beckn:resourceAttributes — extends Resourcebeckn:offerAttributes — extends Offerbeckn:contractAttributes — extends Contractbeckn:commitmentAttributes — extends Commitment (inline in Contract)beckn:performanceAttributes — extends Performance (inside Contract)beckn:considerationAttributes — extends Consideration (inside Contract)beckn:settlementAttributes — extends Settlement (inside Contract)
Reusable core constructs (do not re-model these):
Resource, Offer, Contract, Commitment, Performance, Consideration, SettlementDescriptor, Provider, Attributes, TimePeriodTrackAction, Tracking, SupportInfo, Rating, RatingInputCatalog, DiscoveryContext, TransactionContext
Checklist:
STEP 3 — ARCHITECTURAL SANITY SWEEP
Verify schema separation of concerns:
| Schema Container | Responsibility |
|---|
resourceAttributes | Intrinsic metadata about the resource (what it is, not how it is offered) |
offerAttributes | Commercial terms, eligibility constraints, pricing policy, validity |
contractAttributes | Transaction-level metadata spanning the whole contract lifecycle |
commitmentAttributes | Per-commitment details not captured in the Resource or Offer ref |
performanceAttributes | Execution model specifics (logistics, provisioning, scheduling, geolocation) |
considerationAttributes | Value-exchange specifics beyond monetary amount (e.g., SLA terms, token params) |
settlementAttributes | Discharge mechanism details (gateway ref, blockchain tx, escrow release terms) |
Enforce:
- No graph semantics unless domain genuinely requires linked data
- No presentation logic in protocol schemas
- International neutrality — no hardcoded country/currency assumptions
resourceAttributes must NOT contain pricing — pricing belongs in offerAttributesperformanceAttributes must NOT contain payment — that belongs in considerationAttributes/settlementAttributes- Any modeling exception must be documented in README under Design Rationale
STEP 4 — GENERATE SCHEMA PACK
Folder Structure
Each schema that attaches directly to a v2.1 container gets its own top-level folder with a
v2.1/ version subfolder inside it. This per-schema versioning allows each schema to be upgraded
independently. Sub-schemas referenced only from one parent live in that parent's attributes.jsonschema.yaml.
Shared types go in {domain}-common/.
{domain}/
├── {DomainResource}/ ← attaches to resourceAttributes
│ └── v2.1/
│ ├── attributes.jsonschema.yaml
│ ├── context.jsonld
│ ├── vocab.jsonld
│ ├── profile.json
│ ├── renderer.json
│ ├── README.md
│ └── examples/
│ ├── example-resource.json ← on_discover payload
│ └── example-contract.json ← confirm/status payload (if transactional)
├── {DomainOffer}/ ← attaches to offerAttributes (if needed)
│ └── v2.1/
│ └── ... (same 7-file structure)
├── {DomainContract}/ ← attaches to contractAttributes (if transactional)
│ └── v2.1/
│ └── ...
├── {DomainPerformance}/ ← attaches to performanceAttributes (if needed)
│ └── v2.1/
│ └── ...
├── {domain}-common/ ← shared type definitions used by ≥2 schemas
│ └── {SharedTypeName}/
│ ├── attributes.jsonschema.yaml ← $ref target only
│ └── README.md
└── README.md ← domain pack overview
Naming convention: Schema names use the pattern {Domain}{Container} — e.g., RetailResource,
RetailOffer, RetailContract, RetailPerformance, RetailConsideration, RetailCommitment,
RetailSettlement. Do NOT include "Core" or "Attributes" in the name. The x-beckn-container
annotation already indicates which container the schema extends.
Rule — top-level schemas: A schema is top-level if it attaches directly to one of the seven
v2.1 containers. Each top-level schema gets the full 7-file folder structure under its own
{SchemaName}/v2.1/ directory.
Rule — sub-schemas (single parent): Types referenced only from within one parent schema
live in that parent's attributes.jsonschema.yaml under components/schemas. No separate folder.
Rule — shared types (multiple parents): Types referenced by two or more top-level schemas
live in {domain}-common/{TypeName}/ with only attributes.jsonschema.yaml + README.md.
Rule — cross-schema $ref paths: When a child schema extends a parent via allOf, the
$ref path must account for the versioned folder layout. For example, a FoodAndBeverageResource
extending RetailResource uses:
allOf:
- $ref: '../../RetailResource/v2.1/attributes.jsonschema.yaml#/components/schemas/RetailResource'
Note the ../../ to go up from FoodAndBeverageResource/v2.1/ to the domain root, then
down into RetailResource/v2.1/.
CodedValue pattern: Use for any field whose authority is external (government codes,
commodity classification, standards bodies). Place in {domain}-common/CodedValue/:
CodedValue:
type: object
required: ["@context", "@type", "code"]
properties:
"@context": { type: string, format: uri }
"@type": { type: string }
code: { type: string }
All files must be complete and production-ready. See file specs below.
FILE SPECIFICATIONS
attributes.jsonschema.yaml
- OpenAPI 3.1.1 format
info.version must match the schema pack folder name convention: "2.1.0" for a v2.1/
folder, "2.2.0" for v2.2/, etc. This is the schema pack's own release version —
independent of the Beckn protocol version.x-jsonld-id annotation (flat form) on every property — e.g., x-jsonld-id: "prefix:propName".
Do NOT use the nested form x-jsonld: { "@id": "..." }x-beckn-container on the top-level schema (e.g., x-beckn-container: resourceAttributes)$ref back to core YAML (never inline-copy core schemas)- No container object redefinition
- Sub-schemas defined under
components/schemas in the same file
context.jsonld
vocab.jsonld
- Enumerations only — no structural schema
- Human-readable labels (
rdfs:label) and comments (rdfs:comment) for each enum term
- Import core vocab:
"@import": "https://schema.beckn.io/core/v2/vocab.jsonld"
- Use the same per-schema prefix (
<abbr>:) for all enum class and instance IRIs
profile.json
{
"id": "https://schema.beckn.io/{SchemaName}/v1",
"name": "...",
"version": "{folder-version}.0",
"protocol_version": "2.0",
"semantic_model": "generalised",
"included_schemas": [...],
"discovery_fields": [...],
"indexable_paths": [...],
"filterable_paths": [...],
"sortable_paths": [...],
"privacy_notes": [...]
}
Note protocol_version: "2.0" (the Beckn protocol version — stays at 2.0 because the
generalised model is a non-breaking extension, not a protocol bump) and
semantic_model: "generalised" — both mandatory. The version field is the schema pack's
own release version and must match the folder name convention: for a v2.1/ folder use
"2.1.0", for v2.2/ use "2.2.0", and so on. This keeps profile.json and the
filesystem layout consistent, and makes it unambiguous that protocol and schema pack versions
are separate axes.
renderer.json
Core + attribute bindings for UI rendering. Must include four template properties:
card_template: Moustache template for list/search view (legacy text-based)detail_template: Moustache template for resource detail view (legacy text-based)html: Handlebars HTML template for card/listing rendering in a browser. A self-contained
<div> with class {domain}-{usecase}-resource-card. Must reference domain-specific
resourceAttributes fields, beckn:descriptor, beckn:offers[0].beckn:proposedConsideration
for pricing, and beckn:rating for ratings. Use {{#if}}, {{#each}}, and
{{get "path.with.colons"}} helpers as needed.html_detail: Handlebars HTML template for full-detail panel rendering. Class:
{domain}-{usecase}-resource-detail. Includes all fields from html plus expanded
sections for commitments, performance details, and contract terms.
HTML template generation guidance:
README.md
Header block (required):
# {SchemaName} Schema
**Container:** `Resource.resourceAttributes` (or whichever v2.1 container applies)
**Protocol Version:** 2.0
**Semantic Model:** generalised
**Version:** {folder-version}.0
**Use Cases:** {use case list}
**Tag:** {domain tags, space-separated}
Body must contain:
- Overview — what vertical/use case this covers
- Attachment points — which v2.1 containers are extended and why
- Design rationale — key modeling decisions explained
- Non-goals — what this schema explicitly does NOT model
- Upstream candidates — attributes generic enough for Beckn core promotion
examples/ (minimum 2 files)
example-resource.json — Full on_discover payload:
{
"context": {
"action": "on_discover",
"schema_context": ["https://schema.beckn.io/{SchemaName}/context.jsonld"]
},
"message": {
"catalogs": [{
"@context": "https://schema.beckn.io/core/v2/context.jsonld#generalised",
"@type": "beckn:Catalog",
"beckn:id": "...",
"beckn:resources": [{
"@context": "https://schema.beckn.io/core/v2/context.jsonld#generalised",
"@type": "beckn:Resource",
"beckn:id": "...",
"beckn:descriptor": { ... },
"beckn:resourceAttributes": { ... }
}],
"beckn:offers": [{ ... }]
}]
}
}
example-contract.json — Full on_confirm payload (for transactional schemas):
{
"context": { "action": "on_confirm", "schema_context": [...] },
"message": {
"contract": {
"@context": "https://schema.beckn.io/core/v2/context.jsonld#generalised",
"@type": "beckn:Contract",
"beckn:id": "...",
"beckn:status": "CONFIRMED",
"beckn:parties": [...],
"beckn:commitments": [{ "beckn:ref": "...", "beckn:refType": "RESOURCE", "beckn:commitmentAttributes": { ... } }],
"beckn:consideration": [{ "@type": "beckn:Consideration", "beckn:type": "MONETARY", "beckn:status": "AGREED", ... }],
"beckn:performance": [{ "@type": "beckn:Performance", "beckn:id": "...", "beckn:status": "PLANNED", "beckn:performanceAttributes": { ... } }],
"beckn:contractAttributes": { ... }
}
}
}
STEP 5 — VALIDATE WITH SCHEMA TESTER
After generating all schema files, invoke the beckn-v21-schema-tester skill to run the
four-layer test suite against the generated pack.
The tester will auto-discover schema folders under v2.1/ and run:
- L1 OpenAPI structural checks (including v2.1 container validation)
- L2 JSON-LD prefix resolution (accepting
#generalised context import)
- L3 Cross-file consistency (attributes ↔ context ↔ vocab)
- L4 Example payload validation against core + extension schemas
Fix all failures before the summary step.
STEP 6 — POST-GENERATION SUMMARY
After generating the full schema pack and passing all tests, provide:
Both modes:
- Vertical sanity sweep — confirm each schema handles only its designated concern
- Core alignment confirmation — list every v2.1 core construct referenced (not duplicated)
- Upstream candidates — attributes generic enough for Beckn core promotion
Migration mode additionally:
4. Migration delta table — every v2 field/container and its v2.1 destination
5. Paradigm fit verdict — one paragraph summarising the fit review from Phase C, calling
out any genuine design wins (e.g., cross-domain potential, non-monetary consideration) and
any residual commerce-specific assumptions that were preserved for practical reasons
6. Redistribution decisions — confirm which (if any) field moves were made vs. deferred
RULES (Non-negotiable)
| Rule | Detail |
|---|
| No core duplication | Never re-model Resource, Contract, Performance, Consideration, Settlement, etc. |
| No container redefinition | Only extend resourceAttributes, offerAttributes, contractAttributes, commitmentAttributes, performanceAttributes, considerationAttributes, settlementAttributes |
| Resource neutrality | Resources represent a single committable unit of value — not commerce-specific |
| Commercial isolation | Pricing/terms live in offerAttributes, not resourceAttributes |
| Execution isolation | Logistics/provisioning live in performanceAttributes, not contractAttributes |
| Value-exchange isolation | Payment/token terms in considerationAttributes; discharge records in settlementAttributes |
| International neutrality | Abstract country/currency assumptions unless truly domain-specific |
| Per-schema versioned folder | Each schema gets {SchemaName}/v2.1/ — never a single shared v2.1/ directory |
| Concise schema names | Use {Domain}{Container} (e.g., RetailResource) — no "Core" or "Attributes" suffix |
| One folder per top-level schema | Each container-attached schema gets its own folder with 7 files |
| Per-schema namespace prefix | Use "<abbr>": "https://schema.beckn.io/{SchemaName}#" — never a flat domain prefix |
Flat x-jsonld-id annotations | Use x-jsonld-id: "prefix:prop" — never the nested form x-jsonld: { "@id": "..." } |
| String-form vocab aliases | In context.jsonld, class aliases must be strings "Class": "prefix:Class" — not dicts |
| Generalised context import | Always use "@import": "https://schema.beckn.io/core/v2/context.jsonld#generalised" |
| HTML templates mandatory | renderer.json must include both html and html_detail Handlebars templates |
| Migration is never purely mechanical | v2→v2.1 must include a paradigm fit review (STEP 1-M Phase C) before generating files |
| Migration approval gate | Never generate files in migration mode without presenting the migration summary and receiving user approval |
| No v1 direct migration | v1→v2.1 is always two-step: v1→v2 via beckn-v2-schema, then v2→v2.1 via this skill |
| Ask before assuming | If domain detail is missing, ask — never guess |
REFERENCE FILES
See references/ folder for:
beckn-v2.1-core-primer.md — Summary of the v2.1 generalised model and composability patternsv2-to-v2.1-mapping.md — Field-level migration from v2 Item/Order/Fulfillment/Payment to v2.1
When to Read Reference Files
Always read beckn-v2.1-core-primer.md before generating any schema pack (either mode).
Read v2-to-v2.1-mapping.md at the start of every Migration mode run (STEP 1-M). It is
the canonical field-level mapping reference for Phase B and is also the basis for the
migration summary table shown to the user in Phase D.
Adding New Domain References
When asked, save key modeling decisions as references/{domain-name}.md following the structure:
- v2 → v2.1 field migration table (if applicable)
- Sub-use-case breakdown with Resource/Offer/Contract attribute breakdown per use case
- Design rationale
- Upstream candidates
