ENH: Add errors, warnings, info messages to entity

proto/caosdb/entity/v1alpha1/main.proto

@@ -24,6 +24,16 @@ option  java_multiple_files = true;
 option  java_package        = "org.caosdb.api.entity.v1alpha1";
 package caosdb.entity.v1alpha1;
 
+// Messages are used by server's or client's to transport *transient*
+// information, e.g. general information about a transaction, warnings, or
+// errors.
+message Message {
+  // The code is a machine-readable identifier.
+  string code = 1;
+  // A short description of the message which is indented for human readers.
+  string description = 2;
+}
+
 // Version of an entity.
 message Version {
   // Version id
@@ -32,13 +42,20 @@ message Version {
 
 // This is the main class for CaosDB's entities.
 message Entity {
-  // Entity ID
+  // Entity ID. The entity id is the primary key for all entities.
   string id = 1;
-  // Entity name
+  // Entity name. The entity name is a possibly ambiguous identifier which is
+  // intended for human readers. In some cases, names can be restricted to be
+  // unique when this makes sense, but only as means to prevent the creation of
+  // duplicates.
   string name = 2;
-  // Entity description
+  // Entity description. A short description of the purpose and meaning of an
+  // entity which is intended for human readers.
   string description = 3;
-  // Entity version
+  // Entity version. This entity message represents only one version of a
+  // multitude of versions of the same entity (i.e. they have the same Entity
+  // ID). The different versions represent the change of an entity through
+  // transactions.
   Version version = 4;
   // Entity role (e.g. RecordType, Property, Record)
   string role = 5;
@@ -46,10 +63,27 @@ message Entity {
   string unit = 6;
   // Default datatype of this entity (only used by properties).
   string datatype = 7;
+  // Default value of this entity (only used by properties).
+  string value = 8;
   // Properties of this entity.
-  repeated Property properties = 8;
+  repeated Property properties = 9;
   // Parents of this entity.
-  repeated Parent parents = 9;
+  repeated Parent parents = 10;
+  // Errors for this entity which occurred during the current transaction. The
+  // presence of errors indicates that a transaction was not successful and the
+  // errors describe why this is the case.
+  repeated Message errors = 11;
+  // Warnings for this entity which occurred during the current transaction,
+  // but the transaction was nevertheless successful. The presence of warnings
+  // indicates that the entity is in an undesired or non-standard state itself
+  // or in an undesired or non-standard relation to other entities or the
+  // server's state or  configuration. This might cause errors in the future
+  // and should be remedied if possible.
+  repeated Message warnings = 12;
+  // Info messages for this entity which may inform the client about anything
+  // related to the transaction or the new state of the entity itself or in
+  // relation to other entities or the server's state or configuration.
+  repeated Message infos = 13;
 }
 
 // Property of an entity. Don't confuse with an Entity with role="Property"
@@ -89,7 +123,7 @@ message ByIdRequest {
 
 // Response to a retrieve request
 message RetrieveResponse {
-  // payload of the retrieval
+  // Payload of the retrieval
   Entity entity = 1;
 }
 
@@ -99,7 +133,7 @@ message RetrieveResponse {
 message RetrieveRequest {
   // Wrapped special kind of request.
   oneof wrapped_request {
-    // A single retrieve 
+    // A single retrieve
     ByIdRequest by_id = 1;
   }
 }