docs: response taxonomy working document v0.2 by emmanuelmathot · Pull Request #42 · IFRCGo/monty-stac-extension

emmanuelmathot · 2026-04-16T07:34:16Z

Summary

Working document for the Monty response taxonomy, addressing developmentseed/esa-montandon#12 and contributing to deliverable D1.1 (due KO+4m, July 2026).

What's in this PR

docs/model/response-taxonomy.md — v0.2 working document including:
- Survey of 8 frameworks: OCHA 3W/4W, Sendai Framework, IFRC EPoA/DREF, IASC Cluster system, International Charter, CEMS Rapid Mapping, UNOSAT, and PDNA
- Survey of existing STAC extensions (new in v0.2): Terradue disaster:, absence of CEMS/UNOSAT STAC extensions, and related extensions (sar:, eo:, sat:, processing:, eq:)
- Crosswalk summary table with STAC extension availability column
- Taxonomy structure recommendation: 2-level hierarchy (domain → type), lowercase hyphenated codes, with an extension layering strategy (Charter items declare monty: + disaster:)
- Scope boundary definition: Response = action taken / product produced (vs. Impact = estimated effect)
- Proposed initial response type codes — EO-first (CEMS, Charter, UNOSAT) with humanitarian/financial placeholders
- 8 open questions for team discussion before codes are finalised
.github/prompts/research-response-taxonomy.md — implementation plan for this task

Key findings from framework survey

CEMS is the only framework with stable, published, machine-readable codes (REF, FEP, DEL, GRA, SR) → primary source for EO product codes
International Charter product types align with CEMS but have no formal codes → Monty-assigned codes with CEMS crosswalk
UNOSAT uses a phase-based structure (PSA / Damage Assessment / Population Exposure / Monitoring) → mapped to CEMS phases
IFRC EPoA and IASC Clusters provide the humanitarian sector layer → aligned in hum-* placeholder codes
Sendai Framework is outcome-metric oriented, not an action taxonomy → reference only
PDNA is recovery-planning focused → out of scope for v1, documented as future extension

Key findings from STAC extensions survey (v0.2)

Terradue disaster: extension already covers International Charter items with fields for class (activation/area/acquisition/vap), activation_id, activation_status, and resolution_class — owned by @emmanuelmathot, coordination feasible. Charter Response items in Monty should declare both monty: and disaster: rather than duplicating fields.
No CEMS STAC extension exists — CEMS uses a proprietary REST API. Key fields to carry over into monty:response_detail: product type (REF/FEP/DEL/GRA/SR), monitoring, monitoringNumber, statusCode. Drafting a CEMS STAC profile may be part of SW1.1.
No UNOSAT STAC extension exists — products distributed via HDX with HTML metadata only.
sar:, eo:, sat:, processing: extensions apply to the acquisition/imagery layer (linked via derived_from), not to Response product items.

Open questions (see §5.1 of the document)

Should Monty Charter items formally declare the disaster: extension, or adopt its fields selectively into response_detail?
Is disaster:class (vap) complementary to monty:response_type (eo-charter-gra) — or do they conflict?
Should monitoring variants be separate type codes or a response_detail.monitoring property (preferred, mirrors CEMS API)?
Is a Charter activation (disaster:class = activation) a Monty Event or a Monty Response item?
Should UNOSAT and CEMS use separate codes or shared type codes with a source field?
Should drafting a cems: STAC extension be in scope for SW1.1?

Test plan

Review docs/model/response-taxonomy.md for accuracy of framework summaries
Validate CEMS product codes against CEMS Rapid Mapping Portfolio and CEMS API
Validate Charter fields against Terradue disaster: extension schema
Discuss and resolve open questions 1–4 before next issue (response_detail schema design)
Mark acceptance criteria in developmentseed/esa-montandon#12 once document is approved

🤖 Generated with Claude Code

Survey of 7 humanitarian/EO response frameworks (OCHA 3W, Sendai, IFRC EPoA, IASC Clusters, International Charter, CEMS, UNOSAT, PDNA) with crosswalk analysis, taxonomy structure recommendation, and proposed initial response type codes (EO-first: CEMS, Charter, UNOSAT). Also adds the implementation plan to .github/prompts/ for visibility. Contributes to: developmentseed/esa-montandon#12 (D1.1) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

- Add §2.9 surveying existing STAC extensions: Terradue disaster: extension (Charter), CEMS API fields, absence of UNOSAT STAC work, and related extensions (sar:, eo:, sat:, processing:, eq:) - Update crosswalk table with STAC extension availability column - Revise §3 taxonomy recommendation to include extension layering strategy: Charter items should declare disaster: alongside monty: - Expand open questions to cover disaster: adoption, CEMS STAC gap, and monitoring variant representation Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Move the full disaster: extension field table and object model into §2.5 (International Charter) since that extension is the live data model of the Charter Mapper system. §2.9.1 now cross-references §2.5 to avoid duplication. Also fix fenced code block missing language specifier. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

The sentinel-1 STAC extension is largely deprecated — most fields were superseded by generic sar:/eo:/sat: extensions, and its README explicitly cautions that implementors should only use it if they see specific value. Not relevant for Monty Response items. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

- Replace source-prefixed codes (eo-cems-del, eo-charter-del, etc.) with source-agnostic codes (eo-ref, eo-fep, eo-del, eo-gra, eo-pop, eo-mon, eo-sr, eo-vap) — provenance via derived_from links and disaster: extension fields, not encoded in the type code - Charter activation → Monty Event (not Response item); only VAPs become Response items - eo-vap fallback for Charter VAPs where type cannot be determined; best-effort classification always preferred - eo-mon replaces monitoring variant codes (eo-cems-del-mon etc.) with response_detail.monitoring_number property - Update §3.3 code format principles to document source-agnostic rule - Revise open questions to remove resolved ones, focus on remaining gaps Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

- Close open questions 1-6 with explicit decisions: - Q1/Q2 (Charter VAP classification) → tracked in esa-montandon#9 - Q3 (eo-sr as hazard item) → sub-task of esa-montandon#6 - Q4 (disaster:class complementarity) → accepted design decision - Q5 (cems: extension) → no; CEMS fields go in monty:response_detail - Q6 (hum-protection granularity) → deferred - Add §4.4 Sendai Framework crosswalk: default monty:sendai_targets annotations per response type code across eo-, hum-, and fin- domains with rationale per mapping Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Copilot

Pull request overview

Adds/updates documentation to define a working “Response taxonomy” proposal for the Monty STAC extension, including framework crosswalks and an extension-layering strategy to support EO response products (Charter/CEMS/UNOSAT) and placeholders for humanitarian/financial response.

Changes:

Introduces docs/model/response-taxonomy.md working document with framework + STAC extension survey, proposed code set, and crosswalk guidance.
Adds .github/prompts/research-response-taxonomy.md as a task plan / research prompt for issue #12.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 8 comments.

File	Description
docs/model/response-taxonomy.md	New working document proposing response taxonomy structure, EO-first codes, and integration approach with existing STAC extensions.
.github/prompts/research-response-taxonomy.md	New prompt/plan describing research steps and expected document structure for the response taxonomy task.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

pantierra · 2026-04-29T13:13:13Z

Thanks for getting this together. This is already a great start. I am still making my head around it.

The response_detail seems to be a big vague to me. It is referenced throughout but never actually specified. Maybe it is worth to add a field list, types, required vs. optional. The existing extensions cover some fields, but what's left for response_detail to define is still implicit. For easier understanding it would help to sketch at least the remaining fields, or even all and point to the existing specs.

@pantierra

- Remove .github/prompts/research-response-taxonomy.md (research complete) - Bump doc to v0.5; update status note to 'proposed and pending' - Clarify §2.9.2 CEMS mapping: CEMS items declare monty:+processing:, not disaster:; the disaster: column is a semantic reference point only (response_detail.resolution_class / charter_activation_id carry the values) - Switch §3.2 example to source-agnostic codes (eo-ref/fep/del/gra/vap) - Add §4.4 'response_detail Field Sketch' with fields, types, required vs optional, conventions and JSON examples (addresses @pantierra main comment) - Renumber Sendai Framework Crosswalk to §4.5 and update cross-references - Fix '§4.4 below' wording to plain '§4.4' (now §4.5)

emmanuelmathot · 2026-05-20T14:59:13Z

Thanks @pantierra. both points addressed in 76fe2a9.

On response_detail

a concrete proposed field list
types, required vs. optional, and allowed values/format for each
an "Already covered by" column pointing to fields supplied by disaster: / processing: / sar: / eo: / sat: so we don't duplicate them
conventions (only type is required; stats go to Impact items
two minimal JSON examples (CEMS Delineation and Charter VAP) showing how the layering plays out in practice

Still a first-pass for team review

On the CEMS / disaster: mapping: agreed, your reading was correct. I took the lighter fix you suggested rather than moving everything: §2.9.2 now carries an explicit note that the rightmost column is a semantic reference point (the existing extension field covering the same concept) and that CEMS Response items in Monty declare monty: + processing: only, not disaster:.

Ready for another look when you have a moment.

pantierra

Thanks for bringing in the changes. looks good to me, anything else we can iterate on.

emmanuelmathot and others added 2 commits April 16, 2026 09:33

emmanuelmathot changed the title ~~docs: response taxonomy working document v0.1~~ docs: response taxonomy working document v0.2 Apr 16, 2026

emmanuelmathot and others added 4 commits April 16, 2026 15:46

emmanuelmathot requested a review from Copilot April 22, 2026 07:48

Copilot started reviewing on behalf of emmanuelmathot April 22, 2026 07:48 View session

Copilot AI reviewed Apr 22, 2026

View reviewed changes

emmanuelmathot marked this pull request as ready for review May 20, 2026 14:51

emmanuelmathot requested review from pantierra, ranjan-stha and subinasr May 20, 2026 14:59

pantierra approved these changes May 21, 2026

View reviewed changes

emmanuelmathot merged commit d8cc40c into main May 22, 2026
2 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: response taxonomy working document v0.2#42

docs: response taxonomy working document v0.2#42
emmanuelmathot merged 7 commits into
mainfrom
feat/response-taxonomy

emmanuelmathot commented Apr 16, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

pantierra commented Apr 29, 2026

Uh oh!

emmanuelmathot commented May 20, 2026

Uh oh!

pantierra left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

emmanuelmathot commented Apr 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What's in this PR

Key findings from framework survey

Key findings from STAC extensions survey (v0.2)

Open questions (see §5.1 of the document)

Test plan

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

pantierra commented Apr 29, 2026

Uh oh!

emmanuelmathot commented May 20, 2026

Uh oh!

pantierra left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

emmanuelmathot commented Apr 16, 2026 •

edited

Loading