{
  "openapi": "3.1.0",
  "info": {
    "title": "Umay Ana Institutional API",
    "version": "1.0.0-draft",
    "summary": "Reference API contract for permissioned agricultural field intelligence.",
    "description": "PROPOSED REFERENCE SPECIFICATION — NOT A LIVE PRODUCTION API. Defines B2B contracts for banks, insurers, reinsurers, MRV and green-finance partners.",
    "contact": {
      "email": "enk@umay-ai.com"
    },
    "license": {
      "name": "Reference specification — commercial integration terms required",
      "url": "https://umay-ai.com/en/institutional-api-specification"
    }
  },
  "servers": [
    {
      "url": "https://api.umay-ai.com",
      "description": "Proposed production hostname — illustrative until formally launched"
    }
  ],
  "components": {
    "securitySchemes": {
      "OAuth2ClientCredentials": {
        "type": "oauth2",
        "description": "Proposed B2B client-credentials model.",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://api.umay-ai.com/oauth2/token",
            "scopes": {
              "subject-map:write": "Create/update partner pseudonymous subject mappings.",
              "farmer-context:read": "Read permissioned farmer/farm agricultural context.",
              "field-signals:read": "Read permissioned field signals.",
              "portfolio-risk:read": "Read aggregated portfolio intelligence.",
              "insurance-triage:read": "Read non-decisional claim-triage context.",
              "sustainability:read": "Read permissioned sustainability evidence.",
              "mrv:read": "Read MRV readiness and methodology-mapping status.",
              "metadata:read": "Read dictionary, taxonomy and API metadata."
            }
          }
        }
      }
    },
    "parameters": {
      "RequestId": {
        "name": "X-Request-Id",
        "in": "header",
        "required": false,
        "schema": {
          "type": "string"
        }
      },
      "AsOf": {
        "name": "asOf",
        "in": "query",
        "required": false,
        "schema": {
          "type": "string",
          "format": "date-time"
        }
      },
      "Cursor": {
        "name": "cursor",
        "in": "query",
        "required": false,
        "schema": {
          "type": "string"
        }
      },
      "Limit": {
        "name": "limit",
        "in": "query",
        "required": false,
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 500,
          "default": 100
        }
      }
    },
    "schemas": {
      "ResponseMeta": {
        "type": "object",
        "required": [
          "requestId",
          "generatedAt",
          "apiVersion",
          "decisionBoundary"
        ],
        "properties": {
          "requestId": {
            "type": "string"
          },
          "generatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "apiVersion": {
            "type": "string",
            "example": "1.0.0-draft"
          },
          "dataAsOf": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "dataCoverage": {
            "type": [
              "number",
              "null"
            ],
            "minimum": 0,
            "maximum": 1
          },
          "qualityStatus": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "high",
              "medium",
              "low",
              "insufficient",
              null
            ]
          },
          "decisionBoundary": {
            "type": "string",
            "example": "Contextual decision support only. This response must not be used as the sole basis for automatic credit approval/rejection, claim approval/rejection, underwriting, carbon certification or another high-impact institutional decision."
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "code",
          "message",
          "requestId"
        ],
        "properties": {
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "requestId": {
            "type": "string"
          },
          "details": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": true
          }
        }
      },
      "EvidenceDescriptor": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "recommended",
              "self_recorded",
              "evidence_attached",
              "digitally_corroborated",
              "externally_validated",
              "quantified",
              "certified"
            ]
          },
          "sourceType": {
            "type": "string",
            "enum": [
              "farmer_entered",
              "system",
              "ai_derived",
              "weather_provider",
              "remote_sensing",
              "laboratory",
              "partner",
              "verifier",
              "certification_scheme"
            ]
          },
          "sourceVersion": {
            "type": [
              "string",
              "null"
            ]
          },
          "confidence": {
            "type": [
              "number",
              "null"
            ],
            "minimum": 0,
            "maximum": 1
          },
          "verificationRef": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "LocationContext": {
        "type": "object",
        "properties": {
          "countryCode": {
            "type": [
              "string",
              "null"
            ]
          },
          "region": {
            "type": [
              "string",
              "null"
            ]
          },
          "district": {
            "type": [
              "string",
              "null"
            ]
          },
          "locationPrecision": {
            "type": [
              "string",
              "null"
            ]
          },
          "parcelRef": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "CropContext": {
        "type": "object",
        "properties": {
          "crop": {
            "type": [
              "string",
              "null"
            ]
          },
          "cropType": {
            "type": [
              "string",
              "null"
            ]
          },
          "seasonStage": {
            "type": [
              "string",
              "null"
            ]
          },
          "plantingWindow": {
            "type": [
              "string",
              "null"
            ]
          },
          "harvestEstimate": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "SubjectMappingRequest": {
        "type": "object",
        "required": [
          "partnerSubjectRef",
          "purpose",
          "consentRef"
        ],
        "properties": {
          "partnerSubjectRef": {
            "type": "string",
            "description": "Pseudonymous partner reference; do not send raw PII."
          },
          "purpose": {
            "type": "string",
            "enum": [
              "credit_origination",
              "credit_monitoring",
              "insurance_monitoring",
              "claim_triage",
              "mrv",
              "green_finance",
              "program_monitoring"
            ]
          },
          "consentRef": {
            "type": "string"
          },
          "expiresAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        }
      },
      "SubjectMappingResponse": {
        "type": "object",
        "properties": {
          "mappingId": {
            "type": "string"
          },
          "partnerSubjectRef": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "pending",
              "revoked",
              "expired"
            ]
          },
          "meta": {
            "$ref": "#/components/schemas/ResponseMeta"
          }
        }
      },
      "FarmerContextResponse": {
        "type": "object",
        "properties": {
          "subjectRef": {
            "type": "string"
          },
          "context": {
            "type": "object",
            "properties": {
              "location": {
                "$ref": "#/components/schemas/LocationContext"
              },
              "crop": {
                "$ref": "#/components/schemas/CropContext"
              },
              "weatherExposure": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "fieldRiskTrend": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "sustainabilityEvidenceCompleteness": {
                "type": [
                  "number",
                  "null"
                ],
                "minimum": 0,
                "maximum": 1
              }
            }
          },
          "meta": {
            "$ref": "#/components/schemas/ResponseMeta"
          }
        }
      },
      "FieldSignal": {
        "type": "object",
        "properties": {
          "signalId": {
            "type": "string"
          },
          "subjectRef": {
            "type": [
              "string",
              "null"
            ]
          },
          "signalType": {
            "type": "string"
          },
          "crop": {
            "type": [
              "string",
              "null"
            ]
          },
          "region": {
            "type": [
              "string",
              "null"
            ]
          },
          "observedAt": {
            "type": "string",
            "format": "date-time"
          },
          "severity": {
            "type": [
              "string",
              "null"
            ]
          },
          "payload": {
            "type": "object",
            "additionalProperties": true
          },
          "evidence": {
            "$ref": "#/components/schemas/EvidenceDescriptor"
          }
        }
      },
      "FieldSignalsResponse": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FieldSignal"
            }
          },
          "nextCursor": {
            "type": [
              "string",
              "null"
            ]
          },
          "meta": {
            "$ref": "#/components/schemas/ResponseMeta"
          }
        }
      },
      "PortfolioRiskResponse": {
        "type": "object",
        "properties": {
          "portfolioRef": {
            "type": "string"
          },
          "summary": {
            "type": "object",
            "additionalProperties": true
          },
          "meta": {
            "$ref": "#/components/schemas/ResponseMeta"
          }
        }
      },
      "ClaimTriageContextResponse": {
        "type": "object",
        "properties": {
          "claimRef": {
            "type": "string"
          },
          "triageContext": {
            "type": "object",
            "properties": {
              "recommendedAction": {
                "type": "string"
              },
              "weatherContext": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "fieldObservationCount": {
                "type": "integer"
              },
              "evidenceCoverage": {
                "type": "number",
                "minimum": 0,
                "maximum": 1
              },
              "automaticDecision": {
                "type": "boolean",
                "const": false
              }
            }
          },
          "meta": {
            "$ref": "#/components/schemas/ResponseMeta"
          }
        }
      },
      "SustainabilityEvidenceResponse": {
        "type": "object",
        "properties": {
          "subjectRef": {
            "type": "string"
          },
          "records": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "meta": {
            "$ref": "#/components/schemas/ResponseMeta"
          }
        }
      },
      "MRVReadinessResponse": {
        "type": "object",
        "properties": {
          "subjectRef": {
            "type": "string"
          },
          "readiness": {
            "type": "object",
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "not_started",
                  "partial",
                  "ready_for_partner_review",
                  "externally_validated",
                  "certified"
                ]
              },
              "completeness": {
                "type": "number",
                "minimum": 0,
                "maximum": 1
              },
              "methodologyId": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "methodologyVersion": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "missingFields": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "externalValidationRequired": {
                "type": "boolean",
                "const": true
              }
            }
          },
          "meta": {
            "$ref": "#/components/schemas/ResponseMeta"
          }
        }
      },
      "DictionaryMetadataResponse": {
        "type": "object",
        "properties": {
          "version": {
            "type": "string"
          },
          "fieldCount": {
            "type": "integer"
          },
          "downloadUrls": {
            "type": "object",
            "additionalProperties": true
          },
          "meta": {
            "$ref": "#/components/schemas/ResponseMeta"
          }
        }
      },
      "TaxonomyResponse": {
        "type": "object",
        "properties": {
          "taxonomy": {
            "type": "string"
          },
          "version": {
            "type": "string"
          },
          "items": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "meta": {
            "$ref": "#/components/schemas/ResponseMeta"
          }
        }
      }
    }
  },
  "security": [
    {
      "OAuth2ClientCredentials": []
    }
  ],
  "paths": {
    "/v1/partner-subject-mappings": {
      "post": {
        "tags": [
          "Identity & Consent"
        ],
        "summary": "Create pseudonymous partner subject mapping",
        "operationId": "createPartnerSubjectMapping",
        "security": [
          {
            "OAuth2ClientCredentials": [
              "subject-map:write"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SubjectMappingRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Mapping created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubjectMappingResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Purpose/scope not permitted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/farmer-context/{subjectRef}": {
      "get": {
        "tags": [
          "Farmer Context"
        ],
        "summary": "Get normalized agricultural context",
        "operationId": "getFarmerContext",
        "security": [
          {
            "OAuth2ClientCredentials": [
              "farmer-context:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "subjectRef",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/RequestId"
          },
          {
            "$ref": "#/components/parameters/AsOf"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FarmerContextResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Purpose/scope not permitted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/field-signals": {
      "get": {
        "tags": [
          "Field Signals"
        ],
        "summary": "List permissioned field signals",
        "operationId": "listFieldSignals",
        "security": [
          {
            "OAuth2ClientCredentials": [
              "field-signals:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "subjectRef",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "signalType",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "crop",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "region",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "$ref": "#/components/parameters/Cursor"
          },
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FieldSignalsResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Purpose/scope not permitted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/portfolios/{portfolioRef}/risk-context": {
      "get": {
        "tags": [
          "Portfolio Intelligence"
        ],
        "summary": "Get aggregated agricultural portfolio risk context",
        "operationId": "getPortfolioRiskContext",
        "security": [
          {
            "OAuth2ClientCredentials": [
              "portfolio-risk:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "portfolioRef",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/AsOf"
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PortfolioRiskResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Purpose/scope not permitted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/insurance/claims/{claimRef}/triage-context": {
      "get": {
        "tags": [
          "Insurance"
        ],
        "summary": "Get non-decisional agricultural claim-triage context",
        "operationId": "getClaimTriageContext",
        "security": [
          {
            "OAuth2ClientCredentials": [
              "insurance-triage:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "claimRef",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "subjectRef",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ClaimTriageContextResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Purpose/scope not permitted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/sustainability/{subjectRef}/evidence": {
      "get": {
        "tags": [
          "Sustainability & MRV"
        ],
        "summary": "Get sustainability practice evidence",
        "operationId": "getSustainabilityEvidence",
        "security": [
          {
            "OAuth2ClientCredentials": [
              "sustainability:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "subjectRef",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "practiceCategory",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/Cursor"
          },
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SustainabilityEvidenceResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Purpose/scope not permitted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/mrv/{subjectRef}/readiness": {
      "get": {
        "tags": [
          "Sustainability & MRV"
        ],
        "summary": "Get methodology-specific MRV readiness",
        "operationId": "getMRVReadiness",
        "security": [
          {
            "OAuth2ClientCredentials": [
              "mrv:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "subjectRef",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "methodologyId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MRVReadinessResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Purpose/scope not permitted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/metadata/data-dictionary": {
      "get": {
        "tags": [
          "Metadata"
        ],
        "summary": "Get Agricultural Data Dictionary metadata",
        "operationId": "getDataDictionaryMetadata",
        "security": [
          {
            "OAuth2ClientCredentials": [
              "metadata:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DictionaryMetadataResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Purpose/scope not permitted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/metadata/taxonomies/{taxonomy}": {
      "get": {
        "tags": [
          "Metadata"
        ],
        "summary": "Get versioned institutional taxonomy",
        "operationId": "getTaxonomy",
        "security": [
          {
            "OAuth2ClientCredentials": [
              "metadata:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "taxonomy",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "version",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaxonomyResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Purpose/scope not permitted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "x-umay-proposed-webhooks": {
    "description": "Illustrative future events; not active.",
    "events": [
      "field_signal.created",
      "field_signal.updated",
      "risk_cluster.changed",
      "sustainability_evidence.updated",
      "mrv_readiness.changed"
    ],
    "delivery": {
      "signature": "HMAC-SHA256 proposed",
      "idempotency": "eventId",
      "retry": "controlled retries proposed"
    }
  },
  "x-umay-data-governance": {
    "pii_default": "No raw PII in institutional payloads by default.",
    "subject_identity": "Partner-specific pseudonymous references.",
    "purpose_limitation": "Scopes + partner permissions.",
    "location_policy": "Least precise location necessary.",
    "decision_boundary": "Contextual decision support only. This response must not be used as the sole basis for automatic credit approval/rejection, claim approval/rejection, underwriting, carbon certification or another high-impact institutional decision.",
    "auditability": "Request IDs, provenance and source versions should be retained."
  }
}