> For the complete documentation index, see [llms.txt](https://docs.openg2p.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openg2p.org/products/open-agri-stack/architecture/use-cases.md).

# Use Cases

How data is shared through use cases.

Through the Exchange, farmer data is shared **only through use cases**. A partner never asks for arbitrary data: it asks for a use case it has been assigned, for one farmer, and the farmer consents to the data that use case reads.

<figure><img src="https://3034178245-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJZcdob2emEcLMvLyIxqT%2Fuploads%2Fgit-blob-2057f15476a4e0cc817fa738616a515c7ccddc63%2Fopen-agri-stack-use-cases.svg?alt=media" alt="Use cases. In Partner Management, each partner is assigned the use cases it may use at onboarding: in the example, Bank A has loan-profile@1 and crop-insurance@1; Insurer B has crop-insurance@1. Each use case, defined in the Composite, has a purpose and names the data it reads from each registry: loan-profile@1, for credit assessment, reads personal details and land from the Farmer Registry and crop seasons from the Crop Sown Registry; crop-insurance@1, for insurance, reads land location from the Farmer Registry and crop seasons and measures from the Crop Sown Registry. Data is shared only through a use case assigned to the partner, with the farmer&#x27;s consent for its purpose and data."><figcaption><p>Partners are assigned use cases; a use case names the data it reads from each registry</p></figcaption></figure>

## What a use case is

A **use case** is a named, versioned definition of one kind of data request, published in the [Composite](https://docs.openg2p.org/products/open-agri-stack/composite.md) by the Agri Stack operator. For example `loan-profile@1`, a farmer's loan profile. It says:

* **Why:** its purpose (e.g. credit assessment), which the farmer's consent must match.
* **About whom:** the farmer's ID it takes (the Farmer ID, or the national ID) and any parameters (e.g. a crop season).
* **What:** its **data sources** and, from each, the [data scopes](https://docs.openg2p.org/products/registry/registry/design/data-scopes.md) it needs (and may optionally use).

A **data source** is a system a use case reads. Today every data source is a registry: one source is one search of one registry, and `loan-profile` has three (the Farmer Registry, then two searches of the Crop Sown Registry). Systems other than registries can be added later through connectors ([Generic Exchange](https://docs.openg2p.org/products/open-agri-stack/roadmap/generic-exchange.md)). Adding a registry: [Adding a Registry](https://docs.openg2p.org/products/open-agri-stack/registries/adding-a-registry.md).

* **The answer:** how the data from the registries is put together into one response.

A use case is configuration, not code: adding one is writing a file ([Use-Case Configuration](https://docs.openg2p.org/products/open-agri-stack/composite/use-case-configuration.md)). It is versioned as `name@major`; a change that reads more data is a new major version, which partners must be assigned again and farmers must consent to again.

## Partners are assigned use cases at onboarding

A partner that consumes data is **onboarded and approved** in the Exchange's [Partner Management](https://docs.openg2p.org/platform/platform-services/partner-management.md). Onboarding is, in short:

* **its keys:** the public keys its requests are signed with;
* **the use cases it is assigned:** one policy per use case, with the farmer ID types and longest consent allowed. It lists no purposes: granting a use case grants its purpose.

Both are approved in Partner Management. A partner may be assigned several use cases; adding one later is a new policy, approved the same way, and removing one is revoking its policy ([Creating and Changing Policies](https://docs.openg2p.org/platform/platform-services/partner-management/creating-and-changing-policies.md)). A partner without a policy for a use case is refused.

## The farmer consents to the data

A farmer does not know what `loan-profile@1` means, so the consent is about the data itself: the purpose and, for each registry, the data being shared. The consent request records each item, not only the use case's name, and the partner portal shows the data scopes under **Data requested**. The form the farmer signs is the partner's own; CM staff check that it matches the request before approving. Showing the farmer each item in plain language, field by field, generated from the request, is not built yet ([Roadmap](https://docs.openg2p.org/products/open-agri-stack/roadmap.md)). In the partner portal, staff pick the use case as a **consent template**; the consent records its purpose and data, and the template code only as a label. Any use case with the same purpose can use it, within its data ([consent templates](https://docs.openg2p.org/products/open-agri-stack/architecture/consent.md#consent-templates)).

## Departments see data, not use cases

A department's systems never deal with use cases, and neither does any Consent Manager, the Exchange's included. Its Partner Management and Consent Manager see only the Composite as a partner and, for each request, a consent token with the purpose, the farmer and the registry's data scopes. In the Composite's scope policy, each department decides the most its registry releases; its administrator reads the published use cases to decide it ([Releasing Registry Data to the Composite](https://docs.openg2p.org/products/open-agri-stack/administration/releasing-data-to-the-composite.md)). A new use case, or one that reads more, gets that data only once the departments widen their policies.

**Why a purpose as well as a use case.** The use case is the Exchange's technical bundle (which registries, which data, what answer); the purpose is the reason the data is wanted, and it is what the rest of the system works with:

* **The law:** consent is given for a purpose (purpose limitation, in data-protection laws such as DPDP and GDPR); the farmer agrees to "credit assessment", not to `loan-profile@1`.
* **The departments:** they never see use cases; their policy for the Composite lists the purposes they release data for, and their CM refuses any other.
* **Other ways in:** a partner reading a registry directly, without the Exchange, has no use case either; the purpose is the same concept everywhere in OpenG2P.
* **Stability:** several use cases, and every version of one, can share a purpose, so a department's policy need not change for each.

The purposes are a country list (Master Data's `CONSENT_PURPOSE`), so the Exchange, the departments and partners use the same codes; a use case names one of them.

**What is released for a request:** the use case's data ∩ what the farmer consented to ∩ what each department allows, worked through in [what actually gets released](https://docs.openg2p.org/products/open-agri-stack/architecture/data-sharing-policies.md#what-actually-gets-released).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.openg2p.org/products/open-agri-stack/architecture/use-cases.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
