datastore.proto

syntax = "proto3";

package datastore;

import "google/protobuf/timestamp.proto";

option go_package = "./datastore";

// Notes:
// - A _time series_ is a context defined by a set of metadata (defined in TSMetadata below) that
//   usually does not vary with observaion (time).
// - An _observation_ consists of a set of of metadata (defined in ObsMetadata below) that usually
//   varies with observation (time). Note that for simplicity the observation value itself (such as
//   air temperature value 12.7) is also considered a metadata field (although strictly speaking
//   this is the only field that is just data, not metadata).
// - There is a 1:N relationship between time series and observations:
//   * A given time series (= unique combination of time series metadata fields) is associated with
//     one or more observations.
//   * A given observation (= unique combination of observation metadata fields) is associated with
//     exactly one time series.

service Datastore {
  rpc PutObservations(PutObsRequest) returns (PutObsResponse);
  rpc GetObservations(GetObsRequest) returns (GetObsResponse);
}

//---------------------------------------------------------------------------

message Point { // horizontal position
  double lat = 1; // latitude degrees in range [-90, 90]
  double lon = 2; // longitude degrees in range [-180, 180]
}

message Polygon { // horizontal area; three or more points
  repeated Point points = 1;
}

message TimeInterval {
  google.protobuf.Timestamp start = 1;
  google.protobuf.Timestamp end = 2;
}

message Link {
  string href = 1;
  string rel = 2;
  string type = 3;
  string hreflang = 4;
  string title = 5;
}

message TSMetadata {
  string version = 1;
  string type = 2;
  string title = 3;
  string summary = 4;
  string keywords = 5;
  string keywords_vocabulary = 6;
  string license = 7;
  string conventions = 8;
  string naming_authority = 9;
  string creator_type = 10;
  string creator_name = 11;
  string creator_email = 12;
  string creator_url = 13;
  string institution = 14;
  string project = 15;
  string source = 16;
  string platform = 17;
  string platform_vocabulary = 18;
  string standard_name = 19;
  string unit = 20;
  string instrument = 21;
  string instrument_vocabulary = 22;
  repeated Link links = 23;
}

message ObsMetadata {
  string id = 1;
  oneof geometry {
    Point geo_point = 2;
    Polygon geo_polygon = 3;
  }
  google.protobuf.Timestamp pubtime = 4;
  string data_id = 5;
  string history = 6;
  string metadata_id = 7;
  oneof obstime {
    google.protobuf.Timestamp obstime_instant = 8;
    //TimeInterval obstime_interval = 9; -- unsupported for now
  }
  string processing_level = 10;
  string value = 11;
}

//---------------------------------------------------------------------------

message Metadata1 { // denormalized (more redundancy)
  TSMetadata ts_mdata = 1;
  ObsMetadata obs_mdata = 2;
}

message Metadata2 { // normalized  (less redundancy)
  TSMetadata ts_mdata = 1;
  repeated ObsMetadata obs_mdata = 2;
}

//---------------------------------------------------------------------------

message PutObsRequest {
  repeated Metadata1 observations = 1;
}

message PutObsResponse {
  int32 status = 1;
  string error = 2; // any error description (empty on success)
}

//---------------------------------------------------------------------------

message GetObsRequest {
  TimeInterval interval = 1; // only return observations in this time range
  Polygon inside = 2; // if specified, only return observations in this area
  repeated string platforms = 3; // if specified, only return observations matching any of these platform patterns
  repeated string standard_names = 4; // if specified, only return observations matching any of these standard names
  repeated string instruments = 5; // if specified, only return observations matching any of these instruments
  repeated string processing_levels = 6; // if specified, only return observations matching any of these processing levels
  // TODO: add search filters for other metadata
}


message GetObsResponse {
  int32 status = 1;
  string error = 2; // any error description (empty on success)
  repeated Metadata2 observations = 3;
}