Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Data Scopes

Consent data scopes — named groups of a registry's own fields, independent of any output standard

A data scope is what a consent, and a partner's access policy in Partner Management (PM), names when it says which data a partner may receive from a registry. In the OpenG2P Registry a scope is a named group of the registry's own fields — not a key of a DCI record or of any other output format. The registry keeps a scope catalogue that maps each scope ID to its fields, version by version, and filters every record to the consented fields before rendering it in any output format.

So:

  • a consent or a policy never depends on how a record is rendered (DCI today, another standard tomorrow);

  • a field can be renamed in the registry without touching any consent or policy;

  • a scope can be narrowed at any time, and widening it never reaches consents given before.

Scopes are used only when a partner reads the registry (partner API), for four things:

  • Consent: a farmer consents to scopes, with labels a person understands ("Land parcels"), never to field names.

  • The department's limit: the registry's scope policy for a partner in PM lists the most it releases to that partner, whatever a consent grants: only consent ∩ policy is released. A sharing without consent (a mandate, or searches across subjects) is limited by scopes the same way.

  • Releasing only what is needed: every record is filtered to the allowed scopes' fields before it is sent.

  • A published catalogue: partners, PM and the Composite read what the registry can share and what each scope means; use cases and policies name scopes, so the registry can change its fields without breaking them.

Staff access does not use scopes: in the staff portal, what a user sees is set by IAM roles and data policies.

Scope IDs

A scope ID is <consent_data_controller>.<name>, for example farmer-registry.land or crop-sown-registry.crop_season.

  • <consent_data_controller> is the registry's data-controller ID, named in consent grants and in partners' PM scope policies: setting consent_data_controller, Helm value global.consentDataController, which defaults to the registry variant (global.registryVariant).

  • <name> is letters, digits, _ and -.

A scope ID is permanent: it is never renamed and never reused for something else. Its label and description may change. A registry ignores scope IDs from another controller's namespace and scope IDs it does not know: they grant nothing (fail closed).

Where scopes come from

Default scopes — one per register section. Without a catalogue, the registry offers one scope per register section: <controller>.<section_mnemonic>, covering every field the section shows (its fields are worked out from the section's UI schema). A section that shows nothing shareable (a score display, for example) gives no scope.

The extension's catalogue. An extension can ship catalogue files, every *.json in <extension package>/meta_data/data-scopes/ (the setting data_scopes_catalogue_path overrides the directory). Files are merged in name order. A catalogue can:

  • relabel a section scope: an entry named like the section, with a label and description and no fields;

  • exclude section scopes: exclude_section_scopes, a list of section mnemonics, or true for no default scopes at all (only the catalogue's own scopes are offered);

  • add finer scopes: a subset of a section's fields, or fields across sections and registers;

  • declare field renames: field_renames, old reference → new reference (see Changing a scope).

Other top-level keys (for example _notes) are ignored.

Field references

A scope's fields is a list of references to the registry's internal record:

Reference
Means

section:<section_mnemonic>

every field the section shows (a default scope is exactly this)

<Register>.<field>

one column of a register, e.g. Farmer.phone_numbers

<Register>.*

all of a register's own fields, e.g. Land.* (a child register's whole records)

<Register>.documents, <Register>.documents.<label>

the record's documents, all or one label

<Register>.activity.<field>

a column of an activity register's activities, e.g. CropSown.activity.crop

<Register>.context.<field>

a column of a context's current state (the projection), e.g. CropSown.context.stage

<Register>.aggregate.<field>

a column of an aggregate (roll-up) row, e.g. CropSown.aggregate.aggregate_value

<Register> is the register mnemonic. .* works for every form. An aggregate's figures are one JSON column (aggregate_value), so aggregates can be scoped by column only. For activity registers see Activity Register Design.

The catalogue is validated against the extension's models and register sections when it is published. An unknown register, field or section refuses the whole catalogue, listing every problem, and the previously published catalogue stays in force.

Publishing and versions

The services publish the catalogue themselves (the extension package with its meta_data is in every service image): at start-up, and again whenever a running service notices that the register sections or the catalogue changed (checked at most every data_scopes_sync_check_seconds, default 60). Publishing is idempotent:

  • a new scope → version 1, effective now;

  • a scope whose fields changed → a new version, effective now;

  • unchanged fields → nothing;

  • a scope no longer offered → retired: its versions stay, consents that name it keep what it last meant until they expire.

Versions are immutable (the database rejects updating or deleting them) and scopes are never deleted.

Enforcement

For each search item the registry's partner API gets the consent's effective scopes from CM (grant ∩ policy) and reads the consent's issue time (iat, else issued_at). For each scope, the fields allowed are:

fields of the version in effect when the consent was issued ∩ fields of the scope's current version

  • A field added after the consent was given never reaches it (widening is not retroactive).

  • A field removed since (e.g. for privacy) is gone for every consent (backdating a consent cannot widen anything).

  • A renamed field keeps its meaning (see below).

  • For a retired scope its last version stands in for "current".

  • A consent with no issue time reads each scope's first version (the narrowest reading).

The internal record (with its linked child-register records, or the activity, context-state or aggregate row) is filtered to the allowed fields, then rendered. A field outside the consent is null; a linked register's records the consent does not reach become an empty list. The output template never sees a field outside the consent. The consent-subject check runs on the unfiltered record, so identifying fields are used for the check even when no scope lets them out.

Searches across subjects (an activity register's aggregates with no subject, for a benefits run) have no per-person consent: the partners allowed to make them, and their scopes, are configured by the registry operator (dci_bulk_aggregate_partners: sender_id → scope IDs; a bare name means this registry's scope). Those scopes apply at their current versions.

Changing a scope

Change
What to do
Effect on consents and policies

Relabel / redescribe

edit label / description

none

Rename a field (same meaning)

change the reference in the scope and add "field_renames": {"Farmer.phone": "Farmer.phone_number"}

none: the new version records the rename and consents keep reading the field

Narrow (remove a field)

remove it from fields

safe: no consent gets it any more

Widen (add a field)

add it to fields

only consents given after the new version get it

Split or merge

add scopes with new names and drop the old scope

the old scope is retired and keeps honouring its consents; move policies to the new IDs

Rename a scope

not possible

add a new scope and retire the old one, as for a split

A section scope follows its section: when a section's widgets change, the scope gets a new version (with the same rules). Renaming a section retires its default scope; an extension that wants stable IDs names its scopes in the catalogue (referencing the section with section:<mnemonic>), so a renamed section refuses the catalogue instead of silently retiring a scope.

APIs

The catalogue holds field references, never values.

  • Partner API: POST /partner/data_scopes with a signed partner envelope (header, message, signature, checked like every other partner call). The unsigned GET /partner/data_scopes is on in the chart by default: the catalogue holds no data, partners need it anyway, and Partner Management, which has no signing key, reads it to offer scopes as a checklist when policies are written. A deployment that wants its field names private turns it off (Allow Unsigned Read of Data Scope Catalogue, global.partnerDataScopesPublicGetEnabled): the GET then answers HTTP 403 pointing to the POST, and PM falls back to free text.

  • Staff API: GET /data_scopes (and POST /data_scopes/get_data_scopes), for staff tools; the registry's staff portal has no page for it yet.

fields is what the catalogue says; resolved_fields is the concrete field list (sections expanded) that enforcement uses.

Where to see them

  • The Composite console (Agri Stack): Registries, one registry: every scope with its label, its fields, and the use-case sources that need it (required) or may use it (optional). See Composite console.

  • Partner Management: when a scope policy is written, the registry's scopes are offered as a checklist (read from the registry's catalogue).

  • The registry's API: GET /partner/data_scopes (above), as JSON.

  • The registry's own docs: a page per registry lists the scopes it ships, e.g. Farmer Registry.

The registry's staff portal has no data-scopes page.

Who uses scope IDs

  • Partners ask for consent with grants: [{data_controller, data_scopes}], where data_scopes are this registry's scope IDs. See the Consent Manager partner integration guide.

  • Registry administrators set allowed_data_scopes of a partner's scope policy for this registry in Partner Management to scope IDs from the catalogue, through a PM onboarding or policy request. See Partner Management: access policies.

  • CM reads the partner's policy from PM and treats scopes as opaque strings (effective = grant ∩ policy); it needs no change when a registry changes its catalogue.

See also Consent-aware data sharing and Partner APIs.

Last updated

Was this helpful?