Return a governed value

In about ten minutes you will ask the project from Your first assertion which region a synthetic person lives in, and read north from a verified response. Then you will see why no other answer could have come back: the project lists every value the answer may take.

Outcome: A verified residence-region assertion carrying one declared value.
Time: About 10 minutes
Level: Local development with synthetic data
Prerequisites: The project, source, and Registry Evidence left running by Your first assertion

Request the region

Work in first-evidence-assertion/adult-status, where the source and Registry Evidence from Your first assertion are still running. Prepare a request for the residence-region assertion definition:

rstack evidence request prepare residence-region \
  --client tutorial-client \
  --purpose residence-check \
  --subject subject:record-id=adult \
  --name residence-region

Prepared request: .evidence/requests/residence-region/request.json
Prepared verification context: .evidence/requests/residence-region/verification.json
Prepared authorization: .evidence/requests/residence-region/authorization.curl

Send the request, then verify the response before reading it:

rstack evidence api /v1/evidence \
  --client tutorial-client \
  --input .evidence/requests/residence-region/request.json \
  --accept application/jose+json \
  --output residence-region.jws.json
rstack evidence verify residence-region.jws.json \
  --context .evidence/requests/residence-region/verification.json \
  --output residence-region.verified.json

VERIFIED

jq '.supportedValues' residence-region.verified.json

[
  {
    "providesValueFor": "urn:example:concept:residence-region:v1",
    "value": "north"
  }
]

The source holds a birth date and a private address beside the region; the assertion carries only north.

See which values the answer may take

In evidence.yaml, the residence-region definition’s region output is a controlled-category: values lists every value it may carry.

outputs:
  region:
    concept: urn:example:concept:residence-region:v1
    type: controlled-category
    values:
    - north
    - south

A Function that computed any other value would not get it past Registry Evidence. One fixture case proves that by returning a value outside the list; run the region fixtures with their trace:

rstack evidence test . --target local-target.yaml --fixture fixtures/residence-region.yaml --explain

"id": "negative-outside-controlled-values",
"observedResult": {
  "class": "service-unavailable"
},
"reasonCode": "output-refused",

Registry Evidence refused the output, so the caller would have received a refusal, not the value.

See who may ask

The same definition sets a grantCeiling, the grant ceiling: the widest authority any grant may give for it:

purpose: residence-check
grantCeiling:
  authorities:
  - organizational
  actorKinds:
  - service
  valueOrigins:
  - request
  audiences:
  - urn:example:audience:standalone-app

dev-authority.yaml grants one exact request shape within it, to the standalone-service access profile that tutorial-client holds:

- definition: residence-region
  purpose: residence-check
  audienceFrom: authenticated-requester
  representations:
  - signed-jws
  subjectBinding: audience-scoped
  subjects:
  - role: subject
    selectorProfile: record-by-id
    valueOrigin: request

Leave the source and Registry Evidence running; the next tutorial continues with them.

Control who can request evidence