> 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/standards.md). # Standards The open standards Agri Stack uses, where it uses its own formats, and where a standard exists that is still to be explored. Agri Stack is built from many OpenG2P components. This page lists, area by area, which open standard each part follows, which components use it, and where no standard is followed. **Components:** **RP** Registry Platform, and the registries built on it: **FR** Farmer Registry, **CSR** Crop Sown Registry. **Composite** the Composite (partner entry point). **CM** Consent Manager. **PM** Partner Management. **Catalogue (MDS)** the catalogues of reference data. **AWE** Approval Workflow Engine. Plus Keycloak, the Audit Manager, Inji Certify, ODK Central and the cluster's Istio / Nginx. | Status | Meaning | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | **Used** | The standard is followed. | | **Partly** | Followed in large part, adapted, or used as a mapping or inspiration. | | **Own** | Our own format; no standard is applied. | | **To explore** | A standard exists that should be evaluated for adoption. | | **Supported, not deployed** | The software implements the standard, but no deployment turns it on yet (for example, a needed service is not installed). | {% hint style="info" %} Standards for consent itself (consent receipts, data-subject rights, artefact semantics) are covered on the Consent Manager's [standards and best practices](/platform/platform-services/consent-management/design/standards-and-best-practices.md) page and summarised here. {% endhint %} ## Data exchange between systems | Area | Components | Where | Standard | Status | Notes | | ----------------------------------------------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Registry search API | RP (FR, CSR), Composite | FR and CSR partner APIs; the Composite calling them | [DCI](https://standards.spdci.org/) (Digital Convergence Initiative) registry API: signed envelope, `sync/search`, `idtype-value` and `expression` queries | **Used** | Only the synchronous search is offered; DCI's asynchronous search and subscribe/notify are not (subscribe/notify is a [TODO](/products/open-agri-stack/open-items.md)). Filters on activity registers (`subject_id`, crop year, season) are our use of DCI's `expression` query. | | Farmer record | RP (FR) | FR's DCI record (`spdci-extensions-dci:Farmer`) | DCI / SPDCI farmer data model | **Partly** | Follows most of the DCI farmer model (personal details, identifiers, family, farm details). DCI defines more detail than is practical to fill; adds `FARMER_ID` beside the Fayda UIN and declared `main_crops`. | | Crop activity, crop season and season-summary records | RP (CSR) | CSR's DCI records (`spdci-extensions-agri:CropActivity`, `…:CropSeason`, `…:ActivityAggregate`) | — | **Own** | Our own record types under an `spdci-extensions-agri` name; not a published DCI extension. To explore: proposing them as a DCI agriculture extension. | | Composite partner API | Composite | `POST /composite/v1/use-cases/{use_case}/query` | Modelled on the DCI envelope (signed `header` + `message`) | **Own** | The body (subject, parameters, consent) and the response's `data` (shaped per use case) are our own. Publishing a JSON Schema / OpenAPI per use case is a [TODO](/products/open-agri-stack/open-items.md). | | Data publishing to subscribers | RP (FR, CSR), Catalogue (MDS), WebSub hub | Registry outgestion (register records and activity events); catalogue notifications (version published / in effect, release published) | [W3C WebSub](https://www.w3.org/TR/websub/) | **Partly** | Commons-services installs a WebSub hub (`websub.`, G2P-5770) and points the catalogue at it (`catalogue.websubHubUrl`). The registry platform can publish to it, but its chart configures no hub, so registry consumers poll (DCI search) until outgestion is pointed at it: a [TODO](/products/open-agri-stack/open-items.md#registries). | | API descriptions | All services | Every service | [OpenAPI 3](https://spec.openapis.org/oas/latest.html) | **Used** | Generated by FastAPI. | | Payload validation | RP (CSR activity types), Catalogue (MDS; list attribute schemas) | Activity types' payloads | [JSON Schema](https://json-schema.org/) | **Used** | Each activity type's payload is a JSON Schema; schema versions are kept per type. The Composite validates use-case files with strict pydantic models (`core/models.py`, unknown keys rejected), not JSON Schema. | | Plausibility rules | RP (activity registers; CSR's rules) | Each activity register's configuration file | [JSON Logic](https://jsonlogic.com/) | **Used** | Rules (warn or block) over the payload and the context's latest activities, run by a small built-in evaluator. Output records per format are Jinja templates (our own); DCI is one format. | | Field capture | RP (CSR), ODK Central | Crop sowing form | [ODK XForms](https://getodk.github.io/xforms-spec/) via ODK Central | **Used** | | | Network discovery | OAN network layer (not an OpenG2P component) | OAN network layer | [Beckn](https://becknprotocol.io/) | **Used** (outside the registries) | Only for discovering service providers and consumers; never for registry data. | ## Security, identity and trust | Area | Components | Where | Standard | Status | Notes | | -------------------------------- | --------------------------------------------------------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Request signatures | Partners, Composite, RP (FR, CSR partner APIs), PM (keys) | Partner → Composite → registries; responses | JWS ([RFC 7515](https://www.rfc-editor.org/rfc/rfc7515)), detached, over `{header, message}` | **Used** | Algorithms EdDSA ([RFC 8037](https://www.rfc-editor.org/rfc/rfc8037)), ES256 and RS256 ([RFC 7518](https://www.rfc-editor.org/rfc/rfc7518)); `none` and HS\* refused. Every registry partner API call is signed, including `/partner/ingest_data`; one switch (`signature_validation_enabled`) turns checking off for testing only. | | Public keys | PM, CM | Partner Management | JWK / JWKS ([RFC 7517](https://www.rfc-editor.org/rfc/rfc7517)); SPKI PEM | **Used** | CM publishes the key that signs its consent tokens at `/.well-known/jwks.json`. | | Service keystores | Composite, CM | The Composite's and CM's signing keys | PKCS#12 | **Used** | | | Staff and service authentication | Keycloak; RP, PM, CM, Catalogue (MDS), AWE, Composite | Keycloak | OAuth 2.0, OpenID Connect | **Used** | Client credentials for service-to-service admin calls. | | Transport | Istio (cluster) | Cluster | TLS; mutual TLS inside the mesh (Istio) | **Used** | | | National identity | RP (FR), Composite, CM | Farmer subject | Fayda (Ethiopia's national ID, built on MOSIP) FAN | **Used** | The FR farmer ID (`FR-…`) is our own identifier, linked to the FAN. | | Certificates | RP (agent portal), Inji Certify | VC issuance (agent portal, Inji Certify) | [W3C Verifiable Credentials](https://www.w3.org/TR/vc-data-model-2.0/), [OpenID4VCI](https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html) | **Used** | See [VC issuance](/platform/platform-services/vc-issuance.md). | | Credential status | Inji Certify, RP | Revoking a credential when its record changes | [W3C Bitstring Status List](https://www.w3.org/TR/vc-bitstring-status-list/) | **Partly** | Certify keeps a status list; using it when the source record is changed or corrected is an [open item](/products/open-agri-stack/open-items.md). | ## Consent and data-share policy | Area | Components | Where | Standard | Status | Notes | | ---------------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Consent object | Partners, Composite, CM, RP | Partner → registries, validated by CM | JWT ([RFC 7519](https://www.rfc-editor.org/rfc/rfc7519)) signed as JWS; JSON-LD `@context` | **Partly** | The claims (`subject_id`, `purpose`, `grants`, `validity`, `jti`, …) and the JSON-LD vocabulary are OpenG2P's own. | | Consent records and receipts | CM | CM | Kantara Consent Receipt v1.1; ISO/IEC TS 27560 (consent records); ISO/IEC 29184 (online privacy notices and consent) | **Used** | The Consent Manager's consent receipt document (signed when a consent is approved, part of the partner's downloaded consent record) follows them. See [CM standards and best practices](/platform/platform-services/consent-management/design/standards-and-best-practices.md). | | Consent artefact semantics | CM | CM | DEPA / Account Aggregator (granular, revocable, time-bound, fetch semantics) | **Used** | | | Data-subject rights | CM | CM | GDPR principles (purpose limitation, minimisation, access, withdrawal) | **Used** | | | Purposes | CM, Composite, PM | PM policies, consents, use cases | [W3C DPV](https://w3c.github.io/dpv/) (Data Privacy Vocabulary) | **To explore** | Purpose codes (e.g. `credit-assessment`) are our own, kept in the country's Master Data code list `CONSENT_PURPOSE`, from which Partner Management offers them in policies. | | Access policies | PM (held, approved), CM and Composite (enforced) | Partner Management | [W3C ODRL](https://www.w3.org/TR/odrl-model/) | **To explore** | Policies are our own model: scope policies (allowed scopes per registry) and use-case policies (one per partner and use case), each with purposes, subject ID types, signing algorithms and validity. See [data-sharing policies](/products/open-agri-stack/architecture/data-sharing-policies.md). | | Consent decision | CM (decision point), RP (enforcement point) | Registry ↔ CM | PDP / PEP pattern (XACML terminology) | **Partly** | The roles follow the pattern; the `/validate` API is our own. | | Exchange consent tokens | CM (exchange and department roles), Composite | Agri Stack Exchange → department CMs | Compact JWS (RFC 7515), header `typ: consent-token+jwt`; keys published as JWKS (RFC 7517) | **Partly** | A short-lived consent token (called a *receipt* in the API and settings), signed by the Exchange CM per registry grant and verified offline by department CMs; in the spirit of OAuth 2.0 token exchange ([RFC 8693](https://www.rfc-editor.org/rfc/rfc8693)), not an implementation of it. The claims are our own; `sub` is an object, so verify the JWS and read the claims rather than using a standard JWT validator. See [Exchange consent tokens](/platform/platform-services/consent-management/design/exchange-receipts.md). | | Consent scopes | RP (scope catalogue, enforcement), CM, Composite | Each registry's [data scope catalogue](/products/registry/registry/design/data-scopes.md) | — | **Own** | Scopes are named, versioned groups of a registry's own fields, independent of DCI or any other output format. To explore: DPV personal data categories. | ## Catalogues and reference data | Area | Components | Where | Standard | Status | Notes | | ---------------------------------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Lists (reference data) | Catalogue (MDS), RP | [Catalogues](/products/open-agri-stack.md#catalogues-platform-services-and-the-exchange) | — | **Own** | Codes are the country's (e.g. `CROP_TEFF`, `SEASON_MEHER`); the catalogue APIs and list format are our own. | | Lists as concept schemes | Catalogue (MDS) | [Public catalogue](/platform/platform-services/master-data-service/public-catalogue.md#skos-concept-schemes) (`/public/datasets/{code}/skos`) | [W3C SKOS](https://www.w3.org/TR/skos-reference/) (JSON-LD) | **Used** | Opt-in: only lists marked public, at published versions. A `skos:Concept` per entry with `skos:notation`, language-tagged `skos:prefLabel` and `skos:broader`. | | Crop and commodity codes | Catalogue (MDS) | `CROP_COMMODITY` | FAO [AGROVOC](https://agrovoc.fao.org/), FAO Indicative Crop Classification, FAOSTAT commodity codes | **To explore** | As optional mappings from the country's codes. | | Administrative areas | Catalogue (MDS), RP | Catalogues; every activity's location | OCHA COD-AB P-codes (e.g. `ET040611`) | **Used** | The Ethiopia country pack's geography; CC BY-IGO licence (see [Country Packs](/platform/platform-services/master-data-service/country-packs.md#sources-and-licence)). | | Country codes | Catalogue (MDS) | Country pack and geography | [ISO 3166-1](https://www.iso.org/iso-3166-country-codes.html) alpha-3 (e.g. `ETH`) | **Used** | A convention for pack names, not validated. See the [MDS standards](/platform/platform-services/master-data-service/standards.md). | | Shapes | RP (FR), Catalogue (MDS; boundaries in the object store) | FR land parcels; catalogue boundaries (also downloadable per level from the public catalogue) | GeoJSON ([RFC 7946](https://www.rfc-editor.org/rfc/rfc7946)) | **Used** | | | Boundary features API | Catalogue (MDS) | Catalogue geography | [OGC API – Features](https://ogcapi.ogc.org/features/) | **To explore** | Today the public catalogue offers a GeoJSON file per level, not a features API. | | Query API for BI tools | Catalogue (MDS; public catalogue) | Catalogue datasets | [OData](https://www.odata.org/) (OASIS) | **To explore** | Lets Excel, Power BI and Tableau query a dataset live. Not needed while datasets are small and CSV/JSON downloads cover it; ODK Central's OData feed is already consumed by CSR's ODK ingestion. Not for registry or partner data (DCI and consent-scoped APIs). | | Catalogue dataset descriptions | Catalogue (MDS) | [Public catalogue](/platform/platform-services/master-data-service/public-catalogue.md#dcat-catalogue) (`/public/catalog`) | [W3C DCAT](https://www.w3.org/TR/vocab-dcat-3/) (DCAT-AP style, JSON-LD) | **Used** | Opt-in: a `dcat:Dataset` per public list and for the geography when public, with licence, version and a distribution per format (CSV, JSON, SKOS, GeoJSON). Harvestable by CKAN / DCAT harvesters. | | Registry and use-case descriptions | RP, Composite | Registries, use cases | [W3C DCAT](https://www.w3.org/TR/vocab-dcat-3/) | **To explore** | For describing what each registry and use case offers. | ### TODO: agricultural data standards for the catalogues {% hint style="warning" %} **TODO.** The agriculture datasets in the country pack ([openg2p-data](https://github.com/OpenG2P/openg2p-data) `packs/ETH/domains/agriculture`) use our own codes, and only crop codes have a candidate standard noted above. We must look at all of the standards below and decide the best fit for the stack, dataset by dataset. **Preferred direction (later): stay standard-agnostic.** A country picks the standard each dataset follows (its own codes, AGROVOC, ICC, EPPO, …), and the catalogue carries it; registries and other modules must read whichever the country chose, so no module is tied to one standard. Mappings between standards are then catalogue data (e.g. SKOS matches), not code. {% endhint %} Candidates, by dataset: | Datasets | Candidate standards (body) | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Crops and commodities (`CROP_COMMODITY`) | [AGROVOC](https://agrovoc.fao.org/) (FAO); [Indicative Crop Classification ICC 1.1](https://www.fao.org/world-census-agriculture/en/) (FAO, World Programme for the Census of Agriculture 2020); [CPC](https://unstats.un.org/unsd/classifications/Econ/cpc) / [FAOSTAT item codes](https://www.fao.org/faostat/en/#definitions) (UN / FAO); [HS codes](https://www.wcoomd.org/en/topics/nomenclature/overview/what-is-the-harmonized-system.aspx) (WCO); [EPPO codes](https://gd.eppo.int/) | | Crop growth stages (`CROP_GROWTH_STAGE`) | [BBCH scale](https://www.julius-kuehn.de/en/media/publications/bbch-monographs/) (BBCH monograph, Julius Kühn-Institut) | | Pests, diseases, infestation (`INFESTATION_AGENT`, `INFESTATION_TYPE`, `CROP_DAMAGE_CAUSE`, `PEST_CONTROL_ACTION`) | [EPPO codes](https://gd.eppo.int/) (EPPO); [IPPC glossary](https://www.ippc.int/en/publications/622/) (IPPC / FAO); AGROVOC | | Seed varieties and sources (`SEED_VARIETY`, `SEED_TYPE`, `SEED_SOURCE`) | [WIEWS](https://www.fao.org/wiews/en/) (FAO); [Crop Ontology](https://cropontology.org/) (CGIAR); national variety release lists | | Livestock types and breeds (`LIVESTOCK_TYPE`, `LIVESTOCK_BREED`) | [DAD-IS](https://www.fao.org/dad-is/en/) (FAO); AGROVOC | | Soil and land (`SOIL_FERTILITY`) | [World Reference Base for Soil Resources](https://www.fao.org/soils-portal/data-hub/soil-classification/world-reference-base/en/) (FAO / IUSS); [LCCS](https://www.fao.org/4/x0596e/x0596e00.htm) / [ISO 19144](https://www.iso.org/standard/32562.html) land cover (FAO / ISO) | | Agro-ecological zones (`AGRO_ECOLOGICAL_ZONE`) | [GAEZ](https://gaez.fao.org/) (FAO / IIASA), alongside Ethiopia's traditional zones (Bereha, Kolla, Weyna Dega, Dega, Wurch) | | Irrigation, water, land preparation, sowing, cropping system, means of acquisition (`IRRIGATION_*`, `WATER_SOURCE`, `LAND_PREPARATION_METHOD`, `SOWING_METHOD`, `CROPPING_SYSTEM`, `MEANS_OF_ACQUISITION`) | [World Census of Agriculture 2020](https://www.fao.org/world-census-agriculture/en/) concepts and classifications (FAO); AGROVOC | | Fertilizer and machinery (`FERTILIZER_TYPE`, `FARM_MACHINERY`) | [ADAPT](https://adaptframework.org/) (AgGateway); [ISO 11783 (ISOBUS)](https://www.iso.org/standard/57556.html); FAO fertilizer classes ([FAOSTAT fertilizers by product](https://www.fao.org/faostat/en/#data/RFB)) | | Farm activities and income (`SOURCE_OF_INCOME`) | [ISIC Rev.4](https://unstats.un.org/unsd/classifications/Econ/isic) (UN) | | Crop condition (`CROP_CONDITION`) | AGROVOC; national crop assessment scales (e.g. Ethiopian Statistics Service crop surveys) | | Units and geography | [UCUM](https://ucum.org/); [OCHA P-codes](https://humanitarian.atlassian.net/wiki/spaces/imtoolbox/pages/222265609/P-codes) (already used); [UN M49](https://unstats.un.org/unsd/methodology/m49/) (ISO 3166 country codes are already used) | | Cross-cutting | [AgroPortal](https://agroportal.lirmm.fr/) (ontology repository); [GODAN](https://www.godan.info/); [OGC agriculture work](https://www.ogc.org/topics/agriculture/) | For each dataset, the evaluation should record: * the best-fit standard and the body that publishes it; * how well our codes map to it (exact, partial, none); * whether its licence lets us republish it in the public catalogue; * the decision: keep our codes and publish mappings (as SKOS `skos:exactMatch` / `skos:closeMatch` in the [public catalogue](/platform/platform-services/master-data-service/public-catalogue.md)), or adopt the standard's codes; then carry it into the country pack. ## Records, time and measures | Area | Components | Where | Standard | Status | Notes | | ---------------------------------------------- | ----------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------ | -------------- | -------------------------------------------------------------------------------------------------------------------------------- | | Dates and times | All services | Everywhere | ISO 8601 | **Used** | | | Calendar conversion (Ethiopian calendar ships) | RP (CSR) | Activity dates, crop years, season windows | — | **Own** | Our own conversion; season windows follow the CSA Agricultural Sample Survey (Meher, Belg, irrigation). | | Units | RP (FR, CSR) | Areas, quantities | — | **Own** | Hectares and quintals (shipped) by field name (e.g. `area_ha`, `quantity_qt`). To explore: [UCUM](https://ucum.org/) unit codes. | | Occurrence lifecycle | RP (activity registers) | Activity registers (active, superseded, voided) | HL7 FHIR statuses (`amended`, `entered-in-error`) | **Partly** | Used as a mapping for our statuses. | | Observations | RP (activity registers) | Activity registers | ISO 19156 Observations & Measurements; OGC SensorThings; W3C PROV (provenance) | **To explore** | | | Use-case versions | Composite | Composite | [Semantic Versioning](https://semver.org/) | **Used** | Partners call `use_case@major`. | ## Operations | Area | Components | Where | Standard | Status | Notes | | ------------------------ | ------------------------------------------------------------- | --------------------------- | ----------------------------------------------------------------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | Deployment | All services | All services | Kubernetes, Helm, OCI container images | **Used** | See the [OpenG2P deployment model](/operations/deployment/openg2p-deployment-model.md). | | Object storage | Garage (commons); RP, Catalogue (MDS), ODK, Novu, CM | All services | Amazon S3 API | **Used** | Garage replaced MinIO; services use the S3 API in-cluster at `commons-garage:3900`. CM keeps consent evidence in bucket `consent-evidence`. | | Service mesh and ingress | Istio, Nginx | Cluster | Istio, Nginx | **Used** | See [entry point](/products/open-agri-stack/architecture.md#entry-point-the-openg2p-deployment-not-a-separate-api-gateway). | | Audit events | Audit Manager; RP, Catalogue (MDS), CM, Composite emit events | Audit Manager | [CloudEvents 1.0](https://cloudevents.io/) | **Used** | See [Audit Manager](/platform/platform-services/audit-manager.md). | | Distributed tracing | Composite, RP, CM | Composite → registries → CM | [W3C Trace Context](https://www.w3.org/TR/trace-context/), [OpenTelemetry](https://opentelemetry.io/) | **To explore** | Today hops are linked by the request ID in logs and audit events; no `traceparent` is sent. | ## Own formats and standards to explore In one place, what is our own today and what to evaluate: * **Own, with a candidate standard:** * crop activity, crop season and summary records: propose as a DCI agriculture extension; * lists (reference data): map crop codes to AGROVOC / FAO classifications (publishing them as SKOS is done: the public catalogue); * purposes and policies: DPV and ODRL; * units: UCUM. * **Own, by design:** * the Composite's partner API body and response (a JSON Schema per use case is still to be published); * the consent object's claims and the CM `/validate` API; * the calendar conversion (Ethiopian calendar ships). * **Hub installed, publishers not wired:** WebSub (commons installs the hub; the registry platform and the catalogue publish only once pointed at it). * **To explore, not yet used:** OGC API – Features for boundaries, OData for BI tools on the public catalogue, DCAT for registry and use-case descriptions (the public catalogue already uses it), ISO 19156 / SensorThings / PROV for observations, W3C Trace Context and OpenTelemetry for tracing, Bitstring Status List for credentials after a record change. --- # 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/standards.md?ask=&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.