[GitHub] [beam] TheNeuralBit commented on a change in pull request #12553: [BEAM-9615] Add initial schema proto documentation.

[GitBox <gi...@apache.org>]

TheNeuralBit commented on a change in pull request #12553:
URL: https://github.com/apache/beam/pull/12553#discussion_r472406668



##########
File path: model/pipeline/src/main/proto/schema.proto
##########
@@ -32,16 +32,27 @@ option java_package = "org.apache.beam.model.pipeline.v1";
 option java_outer_classname = "SchemaApi";
 
 message Schema {
+  // List of fields for this schema. Two fields may not share a name.
   repeated Field fields = 1;
+  // REQUIRED. An RFC 4122 UUID.
   string id = 2;
   repeated Option options = 3;
 }
 
 message Field {
+  // REQUIRED. Name of this field within the schema.
   string name = 1;
+  // OPTIONAL. Human readable description of this field, such as the query that generated it.
   string description = 2;
   FieldType type = 3;
+  
   int32 id = 4;
+   // OPTIONAL. The position of this field's data in the encoding.
+   // Either no fields in a given row are have encoding position populated,
+   // or all of them are. Used to support backwards compatibility with schema
+   // changes.
+   // Two schemas, one with encoding positions and one without, are equal
+   // if the fields when sorted by encoding position would otherwise be equal.

Review comment:
       
   ```suggestion
      // OPTIONAL. The position of this field's data when encoded, e.g. with beam:coder:row:v1.
      // Either no fields in a given row are have encoding position populated,
      // or all of them are. Used to support backwards compatibility with schema
      // changes.
      // If no fields have encoding position populated the order of encoding is the same as the order in the Schema.
   ```
   
   Added a reference to beam:coder:row:v1 and a note about default behavior. Removed the note about equality - the way equality is implemented in Java, two schemas are only equal if they are exactly the same. There are lower levels of compatibility though, like assignable, equivalent: https://github.com/apache/beam/blob/29ea00e7cbbb6387f6b0c6ee8b112802d1559851/sdks/java/core/src/main/java/org/apache/beam/sdk/schemas/Schema.java#L340-L353

##########
File path: model/pipeline/src/main/proto/schema.proto
##########
@@ -97,7 +108,11 @@ message LogicalType {
 }
 
 message Option {
+  // REQUIRED. Identifier for the option.
   string name = 1;
+  // Optional type specifer for the structure of value.
+  // If not present, assumes no additional configuration is needed
+  // for this option.

Review comment:
       ```suggestion
     // for this option and value is ignored.
   ```

##########
File path: model/pipeline/src/main/proto/schema.proto
##########
@@ -97,7 +108,11 @@ message LogicalType {
 }
 
 message Option {
+  // REQUIRED. Identifier for the option.
   string name = 1;
+  // Optional type specifer for the structure of value.

Review comment:
       ```suggestion
     // OPTIONAL. Type specifer for the structure of value.
   ```




----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org