beckn / beckn/protocol-specifications-v2

Tracking Remaining items from PR 168 review

Open
#170 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
No language data
Stars
15
Forks
13
PR merge metrics
No merged PRs in 30d

Description

@abhimail thanks for the careful pass. The 11 inline points are all addressed in 1f9579f. Two larger meta-points from your summary I'd like to flag:

1. **Distinguishing hard constraints vs governance vs design heuristics.** Partially addressed: the Design Principles preamble now explicitly frames them as direction-setting heuristics, several MUSTs in earlier sections are now SHOULDs where heuristics is the intent, and "Where schemas are published" is labelled as operational publication policy. A more thorough structural pass labelling every section is a larger rewrite; proposing it as a follow-up RFC pass.

2. **Concrete modeling examples** (composition vs new schema, descriptors vs structured attributes, semantic invariance violations, over-structuring vs useful structure, migration/compatibility patterns). Agreed this would strengthen the document. Proposing an "Appendix: Worked Examples" as a follow-up so #168 can ship on schedule.

Happy to tackle either inline now if you'd prefer.

_Originally posted by @ravi-prakash-v in https://github.com/beckn/protocol-specifications-v2/pull/168#issuecomment-4545580475_

Contributor guide

Open the contributing guide

Research direction

Start by reading PR #168 and commit 1f9579f, then review the Design Principles preamble and the sections where MUST/SHOULD language and publication policy are discussed. The follow-up scope is not settled: it may be a structural pass distinguishing heuristics, governance, and constraints, or an Appendix: Worked Examples covering the listed modeling and migration cases. Done means the selected follow-up is agreed and incorporated into the specification.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.