Add protovalidate rules for datasets

apis/datasets/v1/collections.proto

@@ -4,29 +4,38 @@ edition = "2023";
 
 package datasets.v1;
 
+import "buf/validate/validate.proto";
 import "datasets/v1/core.proto";
 import "tilebox/v1/id.proto";
 
 option features.field_presence = IMPLICIT;
 
 // CreateCollectionRequest is used to create a new collection.
 message CreateCollectionRequest {
-  tilebox.v1.ID dataset_id = 1; // The dataset id where the collection should be created.
-  string name = 2; // The name of the collection to create.
+  // The dataset id where the collection should be created.
+  tilebox.v1.ID dataset_id = 1 [(buf.validate.field).required = true];
+  // The name of the collection to create.
+  string name = 2 [(buf.validate.field).string.min_len = 1];
 }
 
 // GetCollectionByNameRequest contains the request parameters for retrieving a single collection by its name.
 message GetCollectionByNameRequest {
-  string collection_name = 1; // The name of the collection to retrieve.
-  bool with_availability = 2; // If true, the response will include the availability interval.
-  bool with_count = 3; // If true, the response will include the number of entries.
-  tilebox.v1.ID dataset_id = 4; // The dataset id.
+  // The name of the collection to retrieve.
+  string collection_name = 1 [(buf.validate.field).string.min_len = 1];
+  // If true, the response will include the availability interval.
+  bool with_availability = 2;
+  // If true, the response will include the number of entries.
+  bool with_count = 3;
+  // The dataset id.
+  tilebox.v1.ID dataset_id = 4 [(buf.validate.field).required = true];
 }
 
 // DeleteCollectionRequest contains the request parameters for deleting a single collection.
 message DeleteCollectionRequest {
-  tilebox.v1.ID collection_id = 1; // The id of the collection to delete.
-  tilebox.v1.ID dataset_id = 2; // The dataset id.
+  // The id of the collection to delete.
+  tilebox.v1.ID collection_id = 1 [(buf.validate.field).required = true];
+  // The dataset id.
+  tilebox.v1.ID dataset_id = 2 [(buf.validate.field).required = true];
 }
 
 // DeleteCollectionResponse is the response to DeleteCollectionRequest.
@@ -35,9 +44,12 @@ message DeleteCollectionResponse {}
 // ListCollectionsRequest contains the request parameters
 // for retrieving a list of all available collections for a given dataset.
 message ListCollectionsRequest {
-  tilebox.v1.ID dataset_id = 1; // The dataset id.
-  bool with_availability = 2; // If true, the response will include the availability interval.
-  bool with_count = 3; // If true, the response will include the number of entries.
+  // The dataset id.
+  tilebox.v1.ID dataset_id = 1 [(buf.validate.field).required = true];
+  // If true, the response will include the availability interval.
+  bool with_availability = 2;
+  // If true, the response will include the number of entries.
+  bool with_count = 3;
 }
 
 // CollectionService is the service definition for the Tilebox datasets service, which provides access to datasets

apis/datasets/v1/core.proto

@@ -56,42 +56,47 @@ message RepeatedAny {
 // DatapointMetadata contains the metadata for a single data point.
 // legacy, only relevant for old endpoints
 message DatapointMetadata {
-  google.protobuf.Timestamp event_time = 1; // The time the message was received by the on-board computer.
-  google.protobuf.Timestamp ingestion_time = 2; // The time the message was ingested by Tilebox.
-  string id = 3 [features.field_presence = EXPLICIT]; // The external id of the datapoint.
-}
-
-// Datapoints is a list of datapoints in a Tilebox dataset, with all data points sharing the same type.
-message Datapoints {
-  repeated DatapointMetadata meta = 1; // A metadata for a datapoint.
-  RepeatedAny data = 2; // The datapoints.
+  // The time the message was received by the on-board computer.
+  google.protobuf.Timestamp event_time = 1;
+  // The time the message was ingested by Tilebox.
+  google.protobuf.Timestamp ingestion_time = 2;
+  // The external id of the datapoint.
+  string id = 3 [features.field_presence = EXPLICIT];
 }
 
 // DatapointPage is a single page of data points of a Tilebox dataset, such as it is returned by a ForInterval query
 message DatapointPage {
-  repeated DatapointMetadata meta = 1; // A metadata for a datapoint.
-  RepeatedAny data = 2; // The datapoints.
-  LegacyPagination next_page = 3 [features.field_presence = EXPLICIT]; // The pagination parameters for the next page.
+  // A metadata for a datapoint.
+  repeated DatapointMetadata meta = 1;
+  // The datapoints.
+  RepeatedAny data = 2;
+  // The pagination parameters for the next page.
+  LegacyPagination next_page = 3 [features.field_presence = EXPLICIT];
 }
 
 // Datapoint is a single datapoint in a Tilebox Dataset
 message Datapoint {
-  DatapointMetadata meta = 1; // A metadata for a datapoint.
-  Any data = 2; // The data.
+  // A metadata for a datapoint.
+  DatapointMetadata meta = 1;
+  // The data.
+  Any data = 2;
 }
 
 // Collection contains basic information about a dataset collection
 message Collection {
-  string legacy_id = 1; // Here for backwards compatibility, to be removed in the future.
+  // Here for backwards compatibility, to be removed in the future.
+  string legacy_id = 1;
   string name = 2;
   tilebox.v1.ID id = 3;
 }
 
 // CollectionInfo contains information about the data available in a dataset collection
 message CollectionInfo {
   Collection collection = 1;
-  tilebox.v1.TimeInterval availability = 2 [features.field_presence = EXPLICIT]; // The time interval for which data is available.
-  uint64 count = 3 [features.field_presence = EXPLICIT]; // Number of entries in the dataset.
+  // The time interval for which data is available.
+  tilebox.v1.TimeInterval availability = 2 [features.field_presence = EXPLICIT];
+  // Number of entries in the dataset.
+  uint64 count = 3 [features.field_presence = EXPLICIT];
 }
 
 // CollectionInfos contains a list of CollectionInfo messages.

apis/datasets/v1/data_access.proto

@@ -4,6 +4,7 @@ edition = "2023";
 
 package datasets.v1;
 
+import "buf/validate/validate.proto";
 import "datasets/v1/core.proto";
 import "datasets/v1/well_known_types.proto";
 import "tilebox/v1/id.proto";
@@ -14,14 +15,19 @@ option features.field_presence = IMPLICIT;
 // Legacy message, to be removed in the future.
 // GetDatasetForIntervalRequest contains the request parameters for retrieving data for a time interval.
 message GetDatasetForIntervalRequest {
-  string collection_id = 1; // The collection id.
+  // The collection id.
+  string collection_id = 1;
 
   // Either time interval or datapoint interval must be set, but not both.
-  tilebox.v1.TimeInterval time_interval = 2; // The time interval for which data is requested.
-  tilebox.v1.IDInterval datapoint_interval = 6; // The datapoint interval for which data is requested.
-
-  LegacyPagination page = 3 [features.field_presence = EXPLICIT]; // The pagination parameters for this request.
-  bool skip_data = 4; // If true, the datapoint data is not returned.
+  // The time interval for which data is requested.
+  tilebox.v1.TimeInterval time_interval = 2;
+  // The datapoint interval for which data is requested.
+  tilebox.v1.IDInterval datapoint_interval = 6;
+
+  // The pagination parameters for this request.
+  LegacyPagination page = 3 [features.field_presence = EXPLICIT];
+  // If true, the datapoint data is not returned.
+  bool skip_data = 4;
   // If true, the datapoint metadata is not returned.
   // If both skip_data and skip_meta are true,
   // the response will only consist of a list of datapoint ids without any additional data or metadata.
@@ -31,64 +37,96 @@ message GetDatasetForIntervalRequest {
 // Legacy message, to be removed in the future.
 // GetDatapointByIdRequest contains the request parameters for retrieving a single data point in a collection by its id.
 message GetDatapointByIdRequest {
-  string collection_id = 1; // The collection id.
-  string id = 2; // The id of the requested data point.
-  bool skip_data = 3; // If true, only the datapoint metadata is returned.
+  // The collection id.
+  string collection_id = 1;
+  // The id of the requested data point.
+  string id = 2;
+  // If true, only the datapoint metadata is returned.
+  bool skip_data = 3;
 }
 
 // QueryByIDRequest contains the request parameters for retrieving a single data point by its id.
 message QueryByIDRequest {
-  repeated tilebox.v1.ID collection_ids = 1; // collection ids to query.
-  tilebox.v1.ID id = 2; // The id of the requested data point.
-  bool skip_data = 3; // If true, only the datapoint metadata is returned.
+  // collection ids to query.
+  repeated tilebox.v1.ID collection_ids = 1 [(buf.validate.field).repeated = {
+    min_items: 1
+    max_items: 100
+  }];
+  // The id of the requested data point.
+  tilebox.v1.ID id = 2 [(buf.validate.field).required = true];
+  // If true, only the datapoint metadata is returned.
+  bool skip_data = 3;
 }
 
 // QueryFilters contains the filters to apply to a query.
 message QueryFilters {
-  // Either a time interval or datapoint interval must be set, but not both.
-  oneof temporal_extent {
-    tilebox.v1.TimeInterval time_interval = 1;
-    tilebox.v1.IDInterval datapoint_interval = 2;
-  }
+  option (buf.validate.message).oneof = {
+    fields: [
+      "time_interval",
+      "datapoint_interval"
+    ]
+    required: true
+  };
+
+  tilebox.v1.TimeInterval time_interval = 1;
+  tilebox.v1.IDInterval datapoint_interval = 2;
 
   SpatialFilter spatial_extent = 3;
 }
 
 // SpatialFilterMode specifies how geometries are compared to a given spatial filter.
 enum SpatialFilterMode {
-  SPATIAL_FILTER_MODE_UNSPECIFIED = 0; // Unspecified spatial filter mode, will default to intersects.
-  SPATIAL_FILTER_MODE_INTERSECTS = 1; // Any geometry that intersects the filter geometry is included.
-  SPATIAL_FILTER_MODE_CONTAINS = 2; // Only geometries fully contained within the filter geometry are included.
+  // Unspecified spatial filter mode, will default to intersects.
+  SPATIAL_FILTER_MODE_UNSPECIFIED = 0;
+  // Any geometry that intersects the filter geometry is included.
+  SPATIAL_FILTER_MODE_INTERSECTS = 1;
+  // Only geometries fully contained within the filter geometry are included.
+  SPATIAL_FILTER_MODE_CONTAINS = 2;
 }
 
 // SpatialCoordinateSystem specifies the coordinate system in which to perform geometry calculations such as
 // intersections.
 enum SpatialCoordinateSystem {
-  SPATIAL_COORDINATE_SYSTEM_UNSPECIFIED = 0; // Unspecified coordinate system, will default to cartesian.
-  SPATIAL_COORDINATE_SYSTEM_CARTESIAN = 1; // Cartesian (lat/lon) coordinate system
-  SPATIAL_COORDINATE_SYSTEM_SPHERICAL = 2; // Spherical (x/y/z) coordinate system
+  // Unspecified coordinate system, will default to cartesian.
+  SPATIAL_COORDINATE_SYSTEM_UNSPECIFIED = 0;
+  // Cartesian (lat/lon) coordinate system
+  SPATIAL_COORDINATE_SYSTEM_CARTESIAN = 1;
+  // Spherical (x/y/z) coordinate system
+  SPATIAL_COORDINATE_SYSTEM_SPHERICAL = 2;
 }
 
 // SpatialFilter defines a spatial filter operation as part of a query.
 message SpatialFilter {
-  Geometry geometry = 1; // The geometry to filter by.
-  SpatialFilterMode mode = 2; // Whether to filter by intersection or containment.
-  SpatialCoordinateSystem coordinate_system = 3; // Coordinate system in which to perform geometry calculations.
+  // The geometry to filter by.
+  Geometry geometry = 1 [(buf.validate.field).required = true];
+  // Whether to filter by intersection or containment.
+  SpatialFilterMode mode = 2 [(buf.validate.field).enum.defined_only = true];
+  // Coordinate system in which to perform geometry calculations.
+  SpatialCoordinateSystem coordinate_system = 3 [(buf.validate.field).enum.defined_only = true];
 }
 
 // QueryRequest contains the request parameters for retrieving data from a Tilebox dataset.
 message QueryRequest {
-  repeated tilebox.v1.ID collection_ids = 1; // collection ids to query.
-  QueryFilters filters = 2; // Filters to apply to the query.
-
-  tilebox.v1.Pagination page = 3 [features.field_presence = EXPLICIT]; // The pagination parameters for this request.
-  bool skip_data = 4; // If true, only datapoint metadata, such as id, time and ingestion_time are returned.
+  // collection ids to query.
+  repeated tilebox.v1.ID collection_ids = 1 [(buf.validate.field).repeated = {
+    min_items: 1
+    max_items: 100
+  }];
+  // Filters to apply to the query.
+  QueryFilters filters = 2;
+
+  // The pagination parameters for this request.
+  tilebox.v1.Pagination page = 3 [features.field_presence = EXPLICIT];
+  // If true, only datapoint metadata, such as id, time and ingestion_time are returned.
+  bool skip_data = 4;
 }
 
 // QueryResultPage is a single page of data points of a Tilebox dataset
 message QueryResultPage {
-  RepeatedAny data = 1; // The datapoints.
-  tilebox.v1.Pagination next_page = 2 [features.field_presence = EXPLICIT]; // The pagination parameters for the next page.
+  // The datapoints.
+  RepeatedAny data = 1;
+  // The pagination parameters for the next page.
+  tilebox.v1.Pagination next_page = 2 [features.field_presence = EXPLICIT];
 }
 
 // DataAccessService provides data access and querying capabilities for Tilebox datasets.

apis/datasets/v1/data_ingestion.proto

@@ -4,32 +4,22 @@ edition = "2023";
 
 package datasets.v1;
 
-import "datasets/v1/core.proto";
+import "buf/validate/validate.proto";
 import "tilebox/v1/id.proto";
 
 option features.field_presence = IMPLICIT;
 
-// Legacy ingest request
-// IngestDatapointsRequest is used to ingest one or multiple datapoints into a collection.
-message IngestDatapointsRequest {
-  tilebox.v1.ID collection_id = 1; // The collection to insert the datapoints into.
-
-  Datapoints datapoints = 2;
-
-  // Whether to allow existing datapoints as part of the request. If true, datapoints that already exist will be
-  // ignored, and the number of such existing datapoints will be returned in the response. If false, any datapoints
-  // that already exist will result in an error. Setting this to true is useful for achieving idempotency (e.g.
-  // allowing re-ingestion of datapoints that have already been ingested in the past).
-  bool allow_existing = 3;
-}
-
 // IngestRequest is used to ingest one or multiple datapoints into a collection.
 message IngestRequest {
-  tilebox.v1.ID collection_id = 1; // The collection to insert the datapoints into.
+  // The collection to insert the datapoints into.
+  tilebox.v1.ID collection_id = 1 [(buf.validate.field).required = true];
 
   // The datapoints to insert. The values here are encoded protobuf messages. The type of the message is determined
   // by the type of the dataset that the specified collection belongs to.
-  repeated bytes values = 2;
+  repeated bytes values = 2 [
+    (buf.validate.field).repeated.max_items = 8192,
+    (buf.validate.field).repeated.items.bytes.min_len = 1
+  ];
 
   // Whether to allow existing datapoints as part of the request. If true, datapoints that already exist will be
   // ignored, and the number of such existing datapoints will be returned in the response. If false, any datapoints
@@ -41,20 +31,24 @@ message IngestRequest {
 // IngestResponse is the response to a IngestRequest, indicating the number of datapoints that were
 // ingested as well as the generated ids for those datapoints.
 message IngestResponse {
-  int64 num_created = 1; // The number of datapoints that were created.
-  int64 num_existing = 2; // The number of datapoints that were ignored because they already existed.
-  repeated tilebox.v1.ID datapoint_ids = 3; // The ids of the datapoints in the same order as the datapoints in the request.
+  // The number of datapoints that were created.
+  int64 num_created = 1;
+  // The number of datapoints that were ignored because they already existed.
+  int64 num_existing = 2;
+  // The ids of the datapoints in the same order as the datapoints in the request.
+  repeated tilebox.v1.ID datapoint_ids = 3;
 }
 
 // DeleteRequest is used to delete multiple datapoints from a collection.
 message DeleteRequest {
-  tilebox.v1.ID collection_id = 1;
-  repeated tilebox.v1.ID datapoint_ids = 2;
+  tilebox.v1.ID collection_id = 1 [(buf.validate.field).required = true];
+  repeated tilebox.v1.ID datapoint_ids = 2 [(buf.validate.field).repeated.max_items = 8192];
 }
 
 // DeleteResponse is used to indicate that multiple datapoints were deleted.
 message DeleteResponse {
-  int64 num_deleted = 1; // The number of datapoints that were deleted.
+  // The number of datapoints that were deleted.
+  int64 num_deleted = 1;
 }
 
 // DataIngestionService provides data ingestion and deletion capabilities for Tilebox datasets.