beckn / beckn/protocol-specifications-v2

User guide required for protocol implementers

Open
#42 1 comment 0 reactions 2 assignees Claimed by @anandp504 View on GitHub
documentation
Dominant language
No language data
Stars
15
Forks
13
PR merge metrics
No merged PRs in 30d

Description

Implementers currently lack a dedicated guide that explains how to adopt and implement the latest changes in the protocol. While the existing documentation covers schema and specifications, it does not provide a step-by-step or conceptual guide to help developers understand how to understand and implement these. Additionally, developers visiting the repository should be able to easily determine whether the use case they are implementing has an associated specialized schema. (maybe this would be solved by the schema explorer)

There is also an open question regarding the expected audience for this guide—whether it should be accessible even to developers unfamiliar with JSON-LD, or whether it can assume a baseline understanding. Regardless, having a clear implementation guide focused specifically on the new changes, along with guidance on locating and using use-case–specific schemas, will significantly improve accessibility and reduce friction for implementers.

**Why This Is Needed**

- Helps implementers transition smoothly to the new protocol version.
- Reduces ambiguity in interpreting updated specifications.
- Makes the protocol more approachable for a broader range of developers.
- Ensures developers can quickly identify relevant schemas for their use cases.
- Minimizes onboarding time and dependency on external support.
- Improves the overall developer experience for newcomers and contributors.

**Proposed Outcome**

- A comprehensive implementation guide that includes:
- A clear overview of the new protocol changes.
- Practical, step-by-step examples and workflows.
- Guidance on discovering which specialized schemas exist and which apply to specific use cases.
- Recommendations, best practices, and common pitfalls.
- Migration guidance for upgrading from previous protocol versions.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.