feat: enforce related-link target roles and align docs/examples#40
Merged
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
Implements issue #39 by formalizing role semantics for rel="related" links between event/hazard/impact items, and aligning schema/docs/examples to that convention.
Changes:
- Adds JSON Schema validation to require exactly one target role (
event/hazard/impact) onrel="related"links. - Updates documentation across multiple source pages and the main README to describe the new related-link role convention.
- Normalizes existing examples to remove multi-role
relatedlinks (e.g., droppingsource/referencefrom link roles).
Reviewed changes
Copilot reviewed 18 out of 18 changed files in this pull request and generated 8 comments.
Show a summary per file
| File | Description |
|---|---|
| json-schema/schema.json | Adds links validation and new definitions to enforce typed related links. |
| README.md | Updates roles guidance and adds related link semantics to docs. |
| docs/model/README.md | Documents cross-item typing via rel="related" link roles. |
| docs/model/sources/README.md | Adds a “Role Conventions” section clarifying item vs link role expectations. |
| docs/model/sources/USGS/README.md | Updates mappings to reflect typed related links; adds corr_id/guid references. |
| docs/model/sources/GDACS/README.md | Updates mappings to include typed related links and corr_id/guid references. |
| docs/model/sources/PDC/README.md | Reorders/clarifies item role examples for consistency. |
| docs/model/sources/IDU/README.md | Cleans up markdown structure and clarifies role ordering. |
| examples/* | Updates related link roles in multiple example items to the new one-role convention. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+280
to
+284
| "not": { | ||
| "type": "object", | ||
| "required": [ | ||
| "rel" | ||
| ], |
There was a problem hiding this comment.
non_related_link currently matches any object that is not {rel: "related"}, including objects with no rel at all. Because this is used under links.items.anyOf, malformed link entries (missing rel/href) will validate as non_related_link, weakening the intended validation. Consider defining a base link schema that requires at least rel and href, then composing it with the not rel=related constraint for the non-related branch.
Comment on lines
+295
to
+299
| "type": "object", | ||
| "required": [ | ||
| "rel", | ||
| "roles" | ||
| ], |
There was a problem hiding this comment.
typed_related_link requires rel and roles but does not require href (or other core Link Object fields). That means a rel="related" link with the right role but no target URI would still pass this schema. If this schema is meant to validate related-item relationships, require href (and optionally type) here, or compose this with a shared base link definition.
Comment on lines
74
to
79
| | Field Name | Type | Description | | ||
| | ----------- | ------ | ------------------------------------------------------------------------------------------------------------------ | | ||
| | roles | [string] | Semantic classification for the linked entity. For `rel="related"` links between Monty items, use `event`, `hazard` or `impact` | | ||
| | occ_type | string | The type of the occurrence. It can be one of the following values: `known`, `potential` | | ||
| | occ_prob | string | It is a qualitative assessment of the likelihood of the linked hazard occurring with the main hazard (e.g. `high`) | | ||
| | occ_probdef | uri | It is a link to the definition of the probability for the hazard relationship | |
There was a problem hiding this comment.
The Link Attributes table lists roles as type [string], but roles is an array of strings (and the rest of the doc uses escaped \[string] for arrays). Update the type and description to reflect an array, consistent with STAC common metadata and the JSON Schema enforcement.
Suggested change
| | Field Name | Type | Description | | |
| | ----------- | ------ | ------------------------------------------------------------------------------------------------------------------ | | |
| | roles | [string] | Semantic classification for the linked entity. For `rel="related"` links between Monty items, use `event`, `hazard` or `impact` | | |
| | occ_type | string | The type of the occurrence. It can be one of the following values: `known`, `potential` | | |
| | occ_prob | string | It is a qualitative assessment of the likelihood of the linked hazard occurring with the main hazard (e.g. `high`) | | |
| | occ_probdef | uri | It is a link to the definition of the probability for the hazard relationship | | |
| | Field Name | Type | Description | | |
| | ----------- | -------- | ------------------------------------------------------------------------------------------------------------------ | | |
| | roles | \[string] | Semantic classification for the linked entity as an array of strings. For `rel="related"` links between Monty items, use `event`, `hazard` or `impact` | | |
| | occ_type | string | The type of the occurrence. It can be one of the following values: `known`, `potential` | | |
| | occ_prob | string | It is a qualitative assessment of the likelihood of the linked hazard occurring with the main hazard (e.g. `high`) | | |
| | occ_probdef | uri | It is a link to the definition of the probability for the hazard relationship | |
Comment on lines
+113
to
+114
| | [`related` link](https://github.com/radiantearth/stac-spec/blob/master/commons/assets.md) | properties.url + "/map" | Link to the USGS interactive map for this event (external resource, not a STAC item relationship) | | ||
| | [`related` link](https://github.com/radiantearth/stac-spec/blob/master/commons/assets.md) | properties.url + "/region" | Link to the USGS regional information for this event (external resource, not a STAC item relationship) | |
There was a problem hiding this comment.
This markdown uses table-row syntax for the properties.url + "/map" and .../region entries but there is no header/separator for a 3-column table in this section, so these lines will render incorrectly. Convert these to a bullet list, or add a proper table header that matches the row shape.
Suggested change
| | [`related` link](https://github.com/radiantearth/stac-spec/blob/master/commons/assets.md) | properties.url + "/map" | Link to the USGS interactive map for this event (external resource, not a STAC item relationship) | | |
| | [`related` link](https://github.com/radiantearth/stac-spec/blob/master/commons/assets.md) | properties.url + "/region" | Link to the USGS regional information for this event (external resource, not a STAC item relationship) | | |
| - [`related` link](https://github.com/radiantearth/stac-spec/blob/master/commons/assets.md) with `properties.url + "/map"`: Link to the USGS interactive map for this event (external resource, not a STAC item relationship) | |
| - [`related` link](https://github.com/radiantearth/stac-spec/blob/master/commons/assets.md) with `properties.url + "/region"`: Link to the USGS regional information for this event (external resource, not a STAC item relationship) |
| | [`via` link](https://github.com/radiantearth/stac-spec/blob/master/commons/assets.md) | properties.url | Link to the USGS event details page | | ||
| | `related` link in [links] | Reference event item | Link to reference event item with `roles: ["event"]` | | ||
| | [monty:corr_id](https://ifrcgo.org/monty-stac-extension/v1.1.1/schema.json#monty:corr_id) | Generated | Generated following the [event correlation](../../correlation_identifier.md) convention | | ||
| | [monty:guid](https://ifrcgo.org/monty-stac-extension/v1.1.1/schema.json#monty:guid) | Generated | Generated following the [guid string](../../global_identififer.md) convention | |
There was a problem hiding this comment.
The relative link ../../global_identififer.md appears to be broken (no such file in docs/model/). Either add the referenced document or update the link to the correct existing GUID documentation path.
Suggested change
| | [monty:guid](https://ifrcgo.org/monty-stac-extension/v1.1.1/schema.json#monty:guid) | Generated | Generated following the [guid string](../../global_identififer.md) convention | | |
| | [monty:guid](https://ifrcgo.org/monty-stac-extension/v1.1.1/schema.json#monty:guid) | Generated | Generated following the [guid string](../../global_identifier.md) convention | |
emmanuelmathot
added a commit
that referenced
this pull request
May 20, 2026
- Tighten non_related_link and typed_related_link to require href via shared base_link definition - Convert USGS related-link table fragments into bullet list (no orphan rows) - Fix global_identifier.md link typo in USGS docs - Update README Link Attributes table: roles type as escaped array, refresh column widths
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
- Tighten non_related_link and typed_related_link to require href via shared base_link definition - Convert USGS related-link table fragments into bullet list (no orphan rows) - Fix global_identifier.md link typo in USGS docs - Update README Link Attributes table: roles type as escaped array, refresh column widths
emmanuelmathot
force-pushed
the
better-roles
branch
from
3020ac0 to
5e80fb8
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
rolesonrelatedlinks for event/hazard/impact item relationships #39 by defining and enforcing role semantics for rel="related" linksChanges
Validation
Closes #39