Skip to content

feat #19: draft Grievance v0.3 with a fixed envelope and a provider slot - #28

Draft
Bhavesh-Suvalaka wants to merge 1 commit into
schema-packs-api-drivenfrom
grievance-v0.3-envelope
Draft

Bhavesh-Suvalaka wants to merge 1 commit into
schema-packs-api-drivenfrom
grievance-v0.3-envelope

Conversation

@Bhavesh-Suvalaka

Copy link
Copy Markdown

Summary

Draft for review. Adds Grievance v0.3 next to v0.2. v0.2 is not touched.

The idea. The pack fixes only what the DSS needs to pick a desk and a call.
Everything a Provider owns sits in one slot, apiProperties.
A new Provider writes its own OpenAPI file and fills that slot. The pack does not change.

schema/Grievance/v0.3/attributes.yaml      # the pack, knows no Provider
├── GrievanceBase       @context, @type, apiProperties (open slot)
├── GrievanceCatalog    informationMode, about, actions, challenge
├── GrievanceRequest    apiProperties + challenge.response
├── GrievanceResponse   apiProperties or challenge.issued
└── ChallengeMethod     the one list of verification methods

api/external/<provider>/grievance/v0.3/openapi.yaml   # points at the pack
├── paths               /init, /status, /support, each with x-beckn-action
├── <Provider>Catalog   pins about.code. Its apiProperties may carry any field
│                       that has a fixed value, or choices to select from and
│                       send as part of an action call
└── <Provider>*Input/Output   the Provider's own fields

Decisions

  1. Fixed envelope, one provider slot. Provider fields live only under apiProperties.
  2. Catalog and messages are separate schemas. The catalog says what a desk needs. A request or response carries only what the call needs.
  3. The Provider file points at the pack. Never the other way. v0.2 had the pack $ref each Provider.
  4. The catalog links an operation, not a schema. actions[].operation is a URI to the OpenAPI operation. One link gives the verb, the request and the response.
  5. scheme becomes about with kind, code, name. "Scheme" is an Indian word, so the kind is now a value, not a field name.
  6. challenge sits outside apiProperties, with a shape the pack owns. A request carries challenge.response. An init reply carries challenge.issued, never the secret.
  7. Each action names the challenge it needs. "challenge": "OTP" on an action points at challenge.methods. A Provider decides per call. init cannot need one.
  8. Closed lists for what the DSS acts on. Each starts small and grows with a new pack version.
Field Values today
actions[].action init, status, support
about.kind Scheme
challenge method OTP
suppliedBy Applicant
 # PM-KISAN catalog
-"scheme": {"code": "PM-KISAN"},
+"about": {"kind": "Scheme", "code": "PM-KISAN", "name": "Pradhan Mantri Kisan Samman Nidhi"},
 "challenge": {"methods": [{"method": "OTP", "suppliedBy": "Applicant", "channel": "SMS", "length": 4, "valueType": "NUMERIC"}]},
 "actions": [
   {"action": "init", ...},
+  {"action": "status",  "challenge": "OTP", ...},
+  {"action": "support", "challenge": "OTP", ...}
 ]
 # PM-KISAN status request
 {
   "@context": ".../Grievance/v0.3/context.jsonld",
   "@type": "openagrinet:Grievance",
-  "scheme": {"code": "PM-KISAN"},
-  "informationMode": "OnDemand",
-  "enrolmentId": "UP12345678A",
+  "challenge": {"response": {"method": "OTP", "value": "7390"}},
+  "apiProperties": {"enrolmentId": "UP12345678A", "case": {"filedOn": "2026-09-28"}}
 }

Evidence

  • Repo checks: check-api-separation.py passes (250 checks). test_pages*.py passes (4 tests).
  • Draft checks: 105 of 105 pass. They cover the examples, the catalog rules, the closed lists, the challenge direction and the operation links.
    These run from a local script. They are not in this PR.
  • Not run: the full site build. It needs Ruby.

Not in this PR

  • profile.json, context.jsonld, vocab.jsonld, renderer.json for v0.3. So the site does not show v0.3, and the v0.3 @context URL does not resolve yet.
  • The 105 checks in scripts/.

🤖 Generated with Claude Code

The pack fixes only what a consumer needs to pick a desk and a call.
Provider fields live under apiProperties. v0.2 is not touched.

- Split the pack into GrievanceCatalog, GrievanceRequest and GrievanceResponse.
- Provider contracts point at the pack, never the other way.
- Catalog actions link an OpenAPI operation and name the challenge they need.
- Replace scheme with about (kind, code, name).
- Keep challenge outside apiProperties, with a shape the pack owns.
- Close the lists for action, about.kind, suppliedBy and the challenge method.
- Add PMFBY and PM-KISAN contracts and examples. PM-KISAN verifies through init.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant