updates based on wigosbox/wis2-gdc implementation

[tomkralidis]

Updates based on discussions with wigosbox / catalogue dev teams:

• a facility has 1..n observingCapabilities
• each observingCapability
  • requires a defined observedProperty
  • has 0..1 deployments (covers unspecified deployments)
  • each deployment has 1 instrument

[joergklausen]

I will look at this beginning of next week and propose an alternative based on the wmdr2-devt model.

…

________________________________ From: david-i-berry ***@***.***> Sent: Tuesday, 21 July 2026 11:41:42 To: wmo-im/wmdr2 ***@***.***> Cc: Klausen Jörg ***@***.***>; Review requested ***@***.***> Subject: Re: [wmo-im/wmdr2] updates based on wigosbox/wis2-gdc implementation (PR #22) @david-i-berry approved this pull request. — Reply to this email directly, view it on GitHub<#22?email_source=notifications&email_token=AIFWXY2RBT3A4NB4S2EDAIL5F43FNA5CNFSNUABKM5UWIORPF5TWS5BNNB2WEL2QOVWGYUTFOF2WK43UKJSXM2LFO4XTINZUGMZDKNJXGMZKM4TFMFZW63VQOJSXM2LFO5PXEZLROVSXG5DFMSSWK5TFNZ2KYZTPN52GK4S7MNWGSY3L#pullrequestreview-4743255732>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/AIFWXY3AMEYLT6MUBIM43YT5F43FNAVCNFSNUABFKJSXA33TNF2G64TZHM2TGMZXGAZDINBVHNEXG43VMU5TIOJTGAZTEOBQG4Z2C5QC>. You are receiving this because your review was requested.Message ID: ***@***.***>

[joergklausen]

Thanks for this update. I agree with the direction that a facility should contain one or more observation-related child objects, and I fully support that the current deployments concept in the main schema needs to be replaced. The current main schema still requires facility-level deployments and instruments, while the PR replaces that with observingCapabilities; that is a useful step away from the old deployment-centric structure.

My main concern is that the proposed model still keeps deployments as a child of observingCapability, with maxItems: 1, and each deployment then requires an instrument. The PR summary says “a facility has 1..n observingCapabilities”, each observing capability requires observedProperty, has 0..1 deployments, and each deployment has one instrument; the proposed observingCapability.yaml and deployment.yaml implement that structure. ([GitHub]1)

In the current wmdr2-devt model we have tried to separate concerns more explicitly:

Facility
  └── ObservationSeries
        ├── observedProperty / observedFeature / observedGeometry
        ├── observingConfigurations[]
        ├── observingProcedures[]
        └── reportingProcedures[]

The reason for ObservationSeries is that it describes the observed thing / observation series: what is observed, in which observed-feature context, and how this observation series is related to programmes, contacts, observing procedures, and reporting procedures. ObservingConfiguration, by contrast, describes the time-bound configuration used to make the observations: method, source of observation, operating status, instrument reference, optional serial number, geometry/instrument position, reference surface, and vertical distance. This is also reflected in the devt README: the useful content of observing-location and instrument-placement history is represented directly in observingConfigurations[], and reusable contacts, instruments, and schedules are registries referenced where they are used. ([GitHub]2)

I would therefore suggest a small conceptual adjustment rather than a large rewrite:

properties:
  observationSeries:   # or observingCapabilities, if the group prefers that term
    type: array
    minItems: 1
    items:
      $ref: observationSeries.yaml

and in observationSeries.yaml:

properties:
  observedProperty:
    ...
  observedFeature:
    ...
  observedGeometry:
    ...
  observingConfigurations:
    type: array
    items:
      $ref: observingConfiguration.yaml

The important point is not necessarily the exact name ObservationSeries versus observingCapabilities. I can live with observingCapabilities if there is a strong preference for that term. But I think “capability” is slightly weaker semantically: it sounds like a potential ability of the facility, whereas the metadata record normally describes an actual observation series. ObservationSeries also avoids overloading deployment, and it gives a natural parent for observed property, observed geometry, programmes, contacts, observing procedures, and reporting procedures.

The more important change is to replace deployments[0..1] with observingConfigurations[0..n]. A single 0..1 deployment is too restrictive because the same observation series can have consecutive instrument/configuration periods, changes in observing method, changes in source of observation, changes in operating status, or changes in instrument position. This does not require a large schema expansion: the current PR’s deployment.yaml already contains many of the needed fields, but they should move into observingConfiguration.yaml.

Concretely, I suggest these schema changes.

1. In wmdrRecordGeoJSON.yaml, replace observingCapabilities with either observationSeries or keep observingCapabilities as the chosen public name, but point it to a schema that represents an observation series, not an instrument deployment. The existing external references to OGC Records, OGC Features, WCMP time, contacts, and links can be retained; a bundled/self-contained schema is useful IMHO, but not strictly necessary.

2. In the child schema, move observingMethod, operatingStatus, sourceOfObservation, and the current deployments content under observingConfigurations[]. These are configuration-level properties, not stable properties of the observation series. The PR currently places observingMethod, operatingStatus, and sourceOfObservation directly on observingCapability, and then nests deployments; I think this should become a flat array of observingConfigurations.

3. Replace deployment.yaml with observingConfiguration.yaml. The useful fields from deployment.yaml can largely be reused: geometry, time, instrument, and reference-surface information. But the concept should no longer be called deployment, and it should not require an instrument. Some observation series are human observations, some have unknown instruments, and some source records do not provide enough information to identify a particular instrument.

4. Move serialNumber out of instrument.yaml and into observingConfiguration.yaml as 0..1. The instrument schema should describe the instrument catalogue entry, for example manufacturer and model. The serial number identifies the instrument instance used in a specific configuration. The PR currently has serialNumber in instrument.yaml, which would make the instrument catalogue instance-specific. This allow the re-use of instruments and instrument instances for different ObservationSeries, which is important for instruments such as spectrometers, or even an AWS providing temperature, wind speed, wind direction, pressure etc.

5. Allow operatingStatus as 0..1 on observingConfiguration, not as a repeating structure and not as a mandatory value. If it is not recorded in the source, we should not invent it.

6. Keep instruments as an optional facility-level registry/catalogue, referenced from observingConfigurations[].instrument. This allows richer documentation without duplicating manufacturer/model details in every observation series.

7. Add optional observingProcedures, reportingProcedures, and schedules either now or in a follow-up PR. These are what allow the richer documentation of sampling frequency, reporting intervals, observing schedules, reporting schedules, data policy, level of data, timeliness, and related procedure-level metadata. They do not need to disturb the current PR’s basic structure.

A minimal aligned structure could look like this:

properties:
  observationSeries:
    type: array
    minItems: 1
    items:
      $ref: observationSeries.yaml

  instruments:
    type: array
    items:
      $ref: instrument.yaml

  schedules:
    type: array
    items:
      $ref: schedule.yaml

# observationSeries.yaml
type: object
properties:
  observedProperty:
    type: string
  observedFeature:
    $ref: observedFeature.yaml
  observedGeometry:
    type: string
  observingConfigurations:
    type: array
    items:
      $ref: observingConfiguration.yaml
  observingProcedures:
    type: array
    items:
      $ref: observingProcedure.yaml
  reportingProcedures:
    type: array
    items:
      $ref: reportingProcedure.yaml
required:
  - observedProperty

# observingConfiguration.yaml
type: object
properties:
  time:
    $ref: 'https://raw.githubusercontent.com/wmo-im/wcmp2/refs/heads/main/schemas/wcmpRecordGeoJSON.yaml#/properties/time'
  observingMethod:
    type: string
  operatingStatus:
    type: string
  sourceOfObservation:
    type: string
  instrument:
    type: string
    description: Reference to facility-level instruments[]
  serialNumber:
    type: string
    description: Serial number of the instrument instance used in this observing configuration
  geometry:
    $ref: 'https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/pointGeoJSON.yaml'
  referenceSurface:
    type: string
  verticalDistanceFromReferenceSurface:
    type: object
    properties:
      value:
        type: number
      uom:
        type: string

This keeps the PR direction but avoids locking the schema into a deployment-centric structure that we have already found too restrictive. In my view, the alignment requires only relatively small changes: rename or reinterpret observingCapability as the observation-series level, replace nested deployments by observingConfigurations[], make instruments a reusable catalogue, and move serial number to the observing configuration. The result remains compatible with the PR’s goal while allowing much richer documentation of observations.

[gaochen-larc]

Question: the ObservedProperty can handle multiple variables, right? A GC instrument can measurement over 100 parameters, we have good use cases from NASA field campaigns. I am sure GAW has similar use cases.

It is not obvious how this schema would handle a complicated instrument to variable relationship, like in AGAGE (see @joergklausen 's use case 7). One deployment need to involved multiple instruments, which may be from different period, and the data was "picked" later by the site scientists.

Research data searches generally operate in two modes: querying a few parameters across all sites (optionally filtered by instrument type), or retrieving all parameters from a single site or facility. This would require a very comprehensive schema, which is also necessary to make data products FAIR. NASA is currently suffering from inadequate schema for handling in-situ measurements from field campaigns.

[luciacap]

Question: the ObservedProperty can handle multiple variables, right? A GC instrument can measurement over 100 parameters, we have good use cases from NASA field campaigns. I am sure GAW has similar use cases.

It is not obvious how this schema would handle a complicated instrument to variable relationship, like in AGAGE (see @joergklausen 's use case 7). One deployment need to involved multiple instruments, which may be from different period, and the data was "picked" later by the site scientists.

Research data searches generally operate in two modes: querying a few parameters across all sites (optionally filtered by instrument type), or retrieving all parameters from a single site or facility. This would require a very comprehensive schema, which is also necessary to make data products FAIR. NASA is currently suffering from inadequate schema for handling in-situ measurements from field campaigns.

The observedProperty handles one variable. You can attach as many variables you want by providing multiple observingCapabilities. Of course depending on the level of details included in the definition it could be that what you define as ten variables correspondes to only one from the code list and viceversa.

In my understanding of Tom's proposal the only way to document the same instrument measuring multiple variables is to repeat the instrument and its deployment information for each variable measured. Since the reuse is not allowed explicitly in the JSON a downstream tool or user could assume the same instrument instance is used if manufacturer, model and serial number are provided and match.

More complex variable-instrument relationships as the one you describe are not supported by the proposed JONS schema.

@tomkralidis please correct if I misunderstood something. Could you also provide the reasoning behind moving the observing method as optional from the Deployment into the observingCapabilities and why the link between the program and the observing Capability was dropped?

[AliGRUAN]

Hi there - having read Jorg's commentary above, I can align with much of what he is discussing - for information, I am the GCOS Networks Manager and am coming at this from a climate use case perspective. I think OSCAR is a very useful tool which, while it has its flaws, offers great capability for discovery of operational and climate-related metadata. I note in the Report of the Task Team on the new OSCAR/Surface that probably the key guiding principle for prioritisation was to guarantee WIGOS (WDQMS, RWC) and NWP operations - while this is a critical function of OSCAR, the system also underpins other activity areas such as climate metadata and potentially holds metadata for members where they may have no national archive in which to store such information (for example, the UK Met Office records all its historical data and metadata in a dedicated archive and uploads a component of that to OSCAR, but many countries do not have this capability). In the specific case of GCOS, I routinely use OSCAR to help manage the GCOS Upper Air Network (GUAN) and the GCOS Surface Network (GSN), whilst the Lead Centre for the GCOS Surface Reference Network (GSRN) uses OSCAR to import station information for reference station intercomparison. As such, while I am appreciative that financial challenges may drive the need to constrain ambition with OSCAR replacement (and equally potentially drive welcome efficiencies), I am cautious on significant changes to OSCAR where that may not fully consider other use cases. I was until relatively recently an OSCAR National Focal Point and it would be interesting to explore with this community what value OSCAR currently adds, including climate and other applications.

Looking at functionalities/features in the TT Report that were highlighted as out of scope of the MVP, it is important therefore to consider where some may impact other use cases and where it is in fact sensible to delay/defer these activities for future potential inclusion:

• Management of code lists and reference data as well as consultation of audit logs are not available via user interface - this item concerns me a little as the functionality potentially refers to all sorts of WMO code lists in standardised formats which, presumably, if uncontrolled could lead to all sorts of non-standard metadata entries that we may not be able to compare and contrast, filter, etc, over historical timescales. One of the key aspects here is what the end product will actually look like and how it will work - if we're talking eg free-text entry for location names, IDs, RAs, etc, then there is a lot of potential for introduction of error here - useful to get confirmation of how this would work
• Auto-suggestion of metadata values based on coordinates (geo-processing services) - very useful functionality but can defer in a limited resource environment
• Dedicated role to manage instruments - it depends what this means exactly. Assuming we are retaining metadata on instruments (important) then does this solely refer to the OSCAR instrument specialist editing role and a single hierarchy role replacing this? If this is the correct interpretation and no material impact is felt to the editing of instruments, then this would be OK - but needs confirming
• Interface from WDQMS providing OSCAR/Surface with the monthly assessed status - as above, this is very useful functionality but could reasonably be deprioritised from the MVP if we are considering a broad range of tools such as WDQMS and the GBON Compliance tool representing the "live" status and OSCAR effectively then being the "static" metadata source.

I believe Jorg has suggested alternative process mappings for WMDR2 and I am largely supportive of them, especially if key items such as "exposure" (WMO Site Classification for each instrument) are missing from the existing design - these are key pieces of information in helping to give a holistic picture of the quality of measurements whether for climate purposes or real time exchange. Indeed, if these sorts of items are omitted or paused under the MVP, even with the intention of reinstating at a later time when resources become available, this would likely see the loss of this climate metadata - and a gap in the record which may be very difficult to recover. Ultimately, much of what I say here depends on an interpretation of what the final outcome might look like in the real world based on what is or isn't hypothetically included in the MVP - but I would urge some caution around too readily discarding some of the OSCAR metadata capability that is extremely useful for climate applications without considerable deliberation.