Skip to content

Update spec according to agreement in Sprint Planning #619

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
HenrikHL wants to merge 4 commits into
base: master
Choose a base branch
from
Open

Update spec according to agreement in Sprint Planning #619

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
a03ba77
Update spec according to agreement in Sprint Planning
HenrikHL Mar 30, 2026
e0ac778
Update ovs_hub_ntf/v1/OVS_HUB_NTF_v1.0.0.yaml
HenrikHL Mar 30, 2026
42287c8
Update ovs_hub_ntf/v1/OVS_HUB_NTF_v1.0.0.yaml
HenrikHL Mar 30, 2026
64d1faf
Update according to review comments
HenrikHL Mar 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
113 changes: 65 additions & 48 deletions ovs_hub_ntf/v1/OVS_HUB_NTF_v1.0.0.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -784,39 +784,48 @@ components:
- '278111222'
- '278173294'
- '234422543'
UNLocationCodes:
locations:
type: array
minItems: 1
description: |
An array of **UN Location codes** to match with this subscription filter. If the array consists of more than one item - a logical **OR** is used between the values when matching.
An array of **UNLocationCode and/or facilitySMDGCode combinations** to match with this subscription filter. If the array consists of more than one item - a logical **OR** is used between the objects when matching.

Comment on lines +787 to 792
Copy link

Copilot AI Mar 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This change removes the previous UNLocationCodes / facilitySMDGCodes filter properties and replaces them with locations, which is a breaking change for the /subscriptions request and response schemas. If this spec follows SemVer (as indicated by the API-Version header examples), consider bumping the contract version and/or keeping the old fields as deprecated for backward compatibility.

Copilot uses AI. Check for mistakes.
If this property is empty, you will be notified for all `UNLocationCodes` that have changes you are authorized to see.
If this property is empty, you will be notified for all `locations` that have changes you are authorized to see.
Copy link

Copilot AI Mar 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

locations sets minItems: 1 but the description says that an empty property results in notifications for all locations. With minItems: 1 an empty array is invalid, so either remove minItems (to allow []) or update the wording to clarify that omitting the property (not an empty array) means ‘all’.

Suggested change
If this property is empty, you will be notified for all `locations` that have changes you are authorized to see.
If this property is omitted, you will be notified for all `locations` that have changes you are authorized to see.

Copilot uses AI. Check for mistakes.
items:
type: string
pattern: ^[A-Z]{2}[A-Z2-9]{3}$
minLength: 5
maxLength: 5
type: object
description: |
The UN Location code specifying where the place is located. The pattern used must be
It is possible to provide the `UNLocationCode`, the `facilitySMDGCode` or both when specifying the location.

- 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)
- 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used
If multiple `UNLocationCode` or `facilitySMDGCode` values need to be provided, then they must be specified as separate objects in the `locations` array.

More info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download)
example: NLAMS
facilitySMDGCodes:
type: array
description: |
An array of **Facility SMDG codes** to match with this subscription filter. If the array consists of more than one item - a logical **OR** is used between the values when matching.
**Condition:** At least one of `UNLocationCode` and/or `facilitySMDGCode` **MUST** be specified, both are also allowed.
Comment on lines +797 to +801
Copy link

Copilot AI Mar 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The locations item schema is an object with no validation to ensure at least one of UNLocationCode or facilitySMDGCode is present, so {} currently satisfies the schema despite the stated condition. Consider encoding the condition with anyOf/oneOf + required (or otherwise enforcing at least one property) to prevent empty objects.

Copilot uses AI. Check for mistakes.
properties:
UNLocationCode:
type: string
pattern: ^[A-Z]{2}[A-Z2-9]{3}$
minLength: 5
maxLength: 5
description: |
Comment on lines +802 to +808
Copy link

Copilot AI Mar 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The locations filter item repeats the same UNLocationCode/facilitySMDGCode structure already defined in #/components/schemas/Location (and again in SubscriptionBodyWithSecret). To reduce duplication and keep the two request/response schemas aligned, consider referencing a shared schema (e.g., $ref to Location or a dedicated LocationFilter).

Copilot uses AI. Check for mistakes.
The UN Location code specifying where the place is located. The pattern used must be

If this property is empty, you will be notified for all `facilitySMDGCodes` that have changes you are authorized to see.
items:
type: string
maxLength: 6
description: |
The code used for identifying the specific facility. This code does not include the UN Location Code.
- 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)
- 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used

More info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download)
example: NLAMS
facilitySMDGCode:
type: string
maxLength: 6
description: |
The code used for identifying the specific facility. This code does not include the UN Location Code.

The codeList used by SMDG is the [SMDG Terminal Code List](https://smdg.org/wp-content/uploads/Codelists/Terminals/SMDG-Terminal-Code-List-v20210401.xlsx)
example: ACT
The codeList used by SMDG is the [SMDG Terminal Code List](https://smdg.org/wp-content/uploads/Codelists/Terminals/SMDG-Terminal-Code-List-v20210401.xlsx)
example: ACT
Comment on lines +795 to +823
Copy link

Copilot AI Mar 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The item schema for locations documents a MUST-condition (“At least one of UNLocationCode and/or facilitySMDGCode MUST be specified”), but the schema does not enforce it (an empty object {} currently validates). Add a schema constraint (e.g., anyOf with required: [UNLocationCode] / required: [facilitySMDGCode], or minProperties: 1) so tooling and validators reflect the documented requirement.

Copilot uses AI. Check for mistakes.
example:
- UNLocationCode: NLAMS
facilitySMDGCode: APMT
- UNLocationCode: DEHAM
- facilitySMDGCode: APMT
required:
- subscriptionReference
- notificationChannel
Expand Down Expand Up @@ -979,39 +988,47 @@ components:
- '278111222'
- '278173294'
- '234422543'
UNLocationCodes:
locations:
type: array
description: |
An array of **UN Location codes** to match with this subscription filter. If the array consists of more than one item - a logical **OR** is used between the values when matching.
An array of **UNLocationCode and/or facilitySMDGCode combinations** to match with this subscription filter. If the array consists of more than one item - a logical **OR** is used between the objects when matching.

If this property is empty, you will be notified for all `UNLocationCodes` that have changes you are authorized to see.
If this property is empty, you will be notified for all `locations` that have changes you are authorized to see.
items:
Comment on lines +991 to 997
Copy link

Copilot AI Mar 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

locations is defined twice (in Subscription and SubscriptionBodyWithSecret) but only the Subscription variant has minItems: 1. This inconsistency will confuse clients and tooling; align the constraints between the two schemas (and ensure they match the intended ‘empty means all’ semantics).

Copilot uses AI. Check for mistakes.
type: string
pattern: ^[A-Z]{2}[A-Z2-9]{3}$
minLength: 5
maxLength: 5
type: object
description: |
The UN Location code specifying where the place is located. The pattern used must be
It is possible to provide the `UNLocationCode`, the `facilitySMDGCode` or both when specifying the location.

- 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)
- 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used
If multiple `UNLocationCode` or `facilitySMDGCode` values need to be provided, then they must be specified as separate objects in the `locations` array.

More info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download)
example: NLAMS
facilitySMDGCodes:
type: array
description: |
An array of **Facility SMDG codes** to match with this subscription filter. If the array consists of more than one item - a logical **OR** is used between the values when matching.
**Condition:** At least one of `UNLocationCode` and/or `facilitySMDGCode` **MUST** be specified, both are also allowed.
properties:
UNLocationCode:
type: string
pattern: ^[A-Z]{2}[A-Z2-9]{3}$
minLength: 5
maxLength: 5
description: |
The UN Location code specifying where the place is located. The pattern used must be

If this property is empty, you will be notified for all `facilitySMDGCodes` that have changes you are authorized to see.
items:
type: string
maxLength: 6
description: |
The code used for identifying the specific facility. This code does not include the UN Location Code.
- 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)
- 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used

More info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download)
example: NLAMS
facilitySMDGCode:
type: string
maxLength: 6
description: |
The code used for identifying the specific facility. This code does not include the UN Location Code.

The codeList used by SMDG is the [SMDG Terminal Code List](https://smdg.org/wp-content/uploads/Codelists/Terminals/SMDG-Terminal-Code-List-v20210401.xlsx)
example: ACT
The codeList used by SMDG is the [SMDG Terminal Code List](https://smdg.org/wp-content/uploads/Codelists/Terminals/SMDG-Terminal-Code-List-v20210401.xlsx)
example: ACT
Copy link

Copilot AI Mar 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same as above: the locations.items schema states a MUST-condition for UNLocationCode/facilitySMDGCode, but the schema does not enforce it, so {} would validate. Add an explicit constraint (anyOf/oneOf with required, or minProperties) so validators and generated clients match the documentation.

Suggested change
example: ACT
example: ACT
anyOf:
- required:
- UNLocationCode
- required:
- facilitySMDGCode

Copilot uses AI. Check for mistakes.
example:
- UNLocationCode: NLAMS
facilitySMDGCode: APMT
- UNLocationCode: DEHAM
- facilitySMDGCode: APMT
required:
- notificationChannel
- weekRange
Expand Down
Loading