Document syntactic restriction for ids in ledger-api proto (#1585)

* document syntactic restriction for ids in ledger-api proto

* address Gerolf's comments

ledger-api/grpc-definitions/com/digitalasset/ledger/api/v1/active_contracts_service.proto

@@ -25,6 +25,7 @@ service ActiveContractsService {
 message GetActiveContractsRequest {
 
   // Must correspond to the ledger ID reported by the Ledger Identification Service.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Required
   string ledger_id = 1;
 
@@ -53,10 +54,12 @@ message GetActiveContractsResponse {
   string offset = 1;
 
   // The workflow that created the contracts.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Optional
   string workflow_id = 2;
 
   // The list of contracts that were introduced by the workflow with ``workflow_id`` at the offset.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Optional
   repeated CreatedEvent active_contracts = 3;
 

ledger-api/grpc-definitions/com/digitalasset/ledger/api/v1/admin/package_management_service.proto

@@ -55,6 +55,7 @@ message ListKnownPackagesResponse {
 message PackageDetails {
  
   // The identity of the DAML-LF package.
+  // Must be a valid PackageIdString (as describe in ``value.proto``).
   // Required
   string package_id = 1;
 

ledger-api/grpc-definitions/com/digitalasset/ledger/api/v1/admin/party_management_service.proto

@@ -66,6 +66,7 @@ message GetParticipantIdRequest {
 message GetParticipantIdResponse {
 
   // Identifier of the participant, which SHOULD be globally unique.
+  // Must be a valid LedgerString (as describe in ``value.proto``).
   string participant_id = 1;
 }
 
@@ -82,6 +83,7 @@ message ListKnownPartiesResponse {
 message PartyDetails {
 
   // The stable unique identifier of a DAML party.
+  // Must be a valid PartyIdString (as described in ``value.proto``).
   // Required
   string party = 1;
 
@@ -99,6 +101,7 @@ message AllocatePartyRequest {
 
   // A hint to the backing participant what party id to allocate. It can be
   // ignored.
+  // Must be a valid PartyIdString (as describe in ``value.proto``).
   // Optional
   string party_id_hint = 1;
 

ledger-api/grpc-definitions/com/digitalasset/ledger/api/v1/command_completion_service.proto

@@ -42,14 +42,17 @@ service CommandCompletionService {
 
 message CompletionStreamRequest {
   // Must correspond to the ledger id reported by the Ledger Identification Service.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Required
   string ledger_id = 1;
 
   // Only completions of commands submitted with the same application_id will be visible in the stream.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Required
   string application_id = 2;
 
   // Non-empty list of parties whose data should be included.
+  // Must be a valid PartyIdString (as described in ``value.proto``).
   // Required
   repeated string parties = 3;
 
@@ -89,6 +92,7 @@ message Checkpoint {
 message CompletionEndRequest {
   // Must correspond to the ledger ID reported by the Ledger Identification Service.
   // Required
+  // Must be a valid LedgerString (as described in ``value.proto``).
   string ledger_id = 1;
 
   // Server side tracing will be registered as a child of the submitted context.

ledger-api/grpc-definitions/com/digitalasset/ledger/api/v1/command_service.proto

@@ -55,6 +55,7 @@ message SubmitAndWaitRequest {
 
 message SubmitAndWaitForTransactionIdResponse {
   // The id of the transaction that resulted from the submitted command.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Required
   string transaction_id = 1;
 }

ledger-api/grpc-definitions/com/digitalasset/ledger/api/v1/commands.proto

@@ -17,25 +17,30 @@ option java_package = "com.digitalasset.ledger.api.v1";
 message Commands {
 
   // Must correspond to the ledger ID reported by the Ledger Identification Service.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Required
   string ledger_id = 1;
 
   // Identifier of the on-ledger workflow that this command is a part of.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Optional
   string workflow_id = 2;
 
   // Uniquely identifies the application (or its part) that issued the command. This is used in tracing
   // across different components and to let applications subscribe to their own submissions only.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Required
   string application_id = 3;
 
-  // Unique command ID. This number should be unique for each new command within an application domain. It can be used for matching
-  // the requests with their respective completions.
+  // Uniquely identified the command. This identifier should be unique for each new command within an
+  // application domain. It can be used for matching the requests with their respective completions.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Required
   string command_id = 4;
 
   // Party on whose behalf the command should be executed. It is up to the server to verify that the
   // authorisation can be granted and that the connection has been authenticated for that party.
+  // Must be a valid PartyIdString (as described in ``value.proto``).
   // Required
   string party = 5;
 
@@ -82,10 +87,12 @@ message ExerciseCommand {
   Identifier template_id = 1;
 
   // The ID of the contract the client wants to exercise upon.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Required
   string contract_id = 2;
 
   // The name of the choice the client wants to exercise.
+  // Must be a valid NameString (as described in ``value.proto``)
   // Required
   string choice = 3;
 
@@ -96,7 +103,7 @@ message ExerciseCommand {
 
 // Create a contract and exercise a choice on it in the same transaction.
 message CreateAndExerciseCommand {
-  // The template of the contract the client wants to create
+  // The template of the contract the client wants to create.
   // Required
   Identifier template_id = 1;
 
@@ -105,6 +112,7 @@ message CreateAndExerciseCommand {
   Record create_arguments = 2;
 
   // The name of the choice the client wants to exercise.
+  // Must be a valid NameString (as described in ``value.proto``).
   // Required
   string choice = 3;
 

ledger-api/grpc-definitions/com/digitalasset/ledger/api/v1/completion.proto

@@ -15,6 +15,7 @@ option java_package = "com.digitalasset.ledger.api.v1";
 // A completion represents the status of a submitted command on the ledger: it can be successful or failed.
 message Completion {
   // The ID of the succeeded or failed command.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Required
   string command_id = 1;
 
@@ -26,6 +27,7 @@ message Completion {
 
   // The transaction_id of the transaction that resulted from the command with command_id.
   // Only set for successfully executed commands.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Optional
   string transaction_id = 3;
 

ledger-api/grpc-definitions/com/digitalasset/ledger/api/v1/event.proto

@@ -35,10 +35,12 @@ message Event {
 message CreatedEvent {
 
   // The ID of this particular event.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Required
   string event_id = 1;
 
   // The ID of the created contract.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Required
   string contract_id = 2;
 
@@ -71,10 +73,12 @@ message CreatedEvent {
 message ArchivedEvent {
 
   // The ID of this particular event.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Required
   string event_id = 1;
 
   // The ID of the archived contract.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Required
   string contract_id = 2;
 
@@ -87,6 +91,8 @@ message ArchivedEvent {
   // question and the parties specified in the `TransactionFilter`. The
   // stakeholders are the union of the signatories and the observers of
   // the contract.
+  // Each one of its elements must be a valid PartyIdString (as descibed
+  // in ``value.proto``).
   // Required
   repeated string witness_parties = 4;
 }
@@ -95,10 +101,12 @@ message ArchivedEvent {
 message ExercisedEvent {
 
   // The ID of this particular event.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Required
   string event_id = 1;
 
   // The ID of the target contract.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Required
   string contract_id = 2;
 
@@ -107,10 +115,12 @@ message ExercisedEvent {
   Identifier template_id = 3;
 
   // The ID of the event in which the target contract has been created.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Required
   string contract_creating_event_id = 4;
 
   // The choice that's been exercised on the target contract.
+  // Must be a valid NameString (as described in ``value.proto``).
   // Required
   string choice = 5;
 
@@ -119,6 +129,7 @@ message ExercisedEvent {
   Value choice_argument = 6;
 
   // The parties that made the choice.
+  // Each element must be a valid PartyIdString (as described in ``value.proto``).
   // Required
   repeated string acting_parties = 7;
 
@@ -141,11 +152,16 @@ message ExercisedEvent {
   // `choice ... controller` syntax, and said controllers are not
   // explicitly marked as observers.
   //
+  // Each element must be a valid PartyIdString (as described in ``value.proto``).
+  //
   // Required
   repeated string witness_parties = 10;
 
   // References to further events in the same transaction that appeared as a result of this ``ExercisedEvent``.
   // It contains only the immediate children of this event, not all members of the subtree rooted at this node.
+  //
+  // Each element must be a valid PartyIdString (as described in ``value.proto``).
+  //
   // Optional
   repeated string child_event_ids = 11;
 

ledger-api/grpc-definitions/com/digitalasset/ledger/api/v1/ledger_configuration_service.proto

@@ -23,6 +23,7 @@ service LedgerConfigurationService {
 message GetLedgerConfigurationRequest {
 
   // Must correspond to the ledger ID reported by the Ledger Identification Service.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Required
   string ledger_id = 1;
 

ledger-api/grpc-definitions/com/digitalasset/ledger/api/v1/ledger_identity_service.proto

@@ -32,6 +32,7 @@ message GetLedgerIdentityResponse {
 
   // The ID of the ledger exposed by the server.
   // Requests submitted with the wrong ledger ID will result in ``NOT_FOUND`` gRPC errors.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Required
   string ledger_id = 1;
 }

ledger-api/grpc-definitions/com/digitalasset/ledger/api/v1/package_service.proto

@@ -28,6 +28,7 @@ service PackageService {
 message ListPackagesRequest {
 
   // Must correspond to the ledger ID reported by the Ledger Identification Service.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Required
   string ledger_id = 1;
 
@@ -40,6 +41,7 @@ message ListPackagesRequest {
 message ListPackagesResponse {
 
   // The IDs of all DAML-LF packages supported by the server.
+  // Each element must be a valid PackageIdString (as described in ``value.proto``).
   // Required
   repeated string package_ids = 1;
 }
@@ -47,10 +49,12 @@ message ListPackagesResponse {
 message GetPackageRequest {
 
   // Must correspond to the ledger ID reported by the Ledger Identification Service.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Required
   string ledger_id = 1;
 
   // The ID of the requested package.
+  // Must be a valid PackageIdString (as described in ``value.proto``).
   // Required
   string package_id = 2;
 
@@ -71,6 +75,7 @@ message GetPackageResponse {
   bytes archive_payload = 2;
 
   // The hash of the archive payload, can also used as a ``package_id``.
+  // Must be a valid PackageIdString (as described in ``value.proto``).
   // Required
   string hash = 3;
 }
@@ -78,10 +83,12 @@ message GetPackageResponse {
 message GetPackageStatusRequest {
 
   // Must correspond to the ledger ID reported by the Ledger Identification Service.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Required
   string ledger_id = 1;
 
   // The ID of the requested package.
+  // Must be a valid PackageIdString (as described in ``value.proto``).
   // Required
   string package_id = 2;
 

ledger-api/grpc-definitions/com/digitalasset/ledger/api/v1/testing/reset_service.proto

@@ -43,6 +43,7 @@ service ResetService {
 
 message ResetRequest {
   // Must correspond to the ledger ID reported by the Ledger Identification Service.
+  // Must be a valid LedgerString (as describe in ``value.proto``).
   // Required
   string ledger_id = 1;
 }

ledger-api/grpc-definitions/com/digitalasset/ledger/api/v1/testing/time_service.proto

@@ -28,6 +28,7 @@ service TimeService {
 message GetTimeRequest {
 
   // Must correspond to the ledger ID reported by the Ledger Identification Service.
+  // Must be a valid LedgerString (as describe in ``value.proto``).
   // Required
   string ledger_id = 1;
 }
@@ -41,6 +42,7 @@ message GetTimeResponse {
 message SetTimeRequest {
 
   // Must correspond to the ledger ID reported by the Ledger Identification Service.
+  // Must be a valid LedgerString (as describe in ``value.proto``).
   // Required
   string ledger_id = 1;
 

ledger-api/grpc-definitions/com/digitalasset/ledger/api/v1/transaction.proto

@@ -18,14 +18,17 @@ option java_package = "com.digitalasset.ledger.api.v1";
 message TransactionTree {
 
   // Assigned by the server. Useful for correlating logs.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Required
   string transaction_id = 1;
 
   // The ID of the command which resulted in this transaction. Missing for everyone except the submitting party.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Optional
   string command_id = 2;
 
   // The workflow ID used in command submission. Only set if the ``workflow_id`` for the command was set.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Optional
   string workflow_id = 3;
 
@@ -40,10 +43,12 @@ message TransactionTree {
   string offset = 6;
 
   // Changes to the ledger that were caused by this transaction. Nodes of the transaction tree.
+  // Each key be a valid LedgerString (as describe in ``value.proto``).
   // Required
   map<string, TreeEvent> events_by_id = 7;
 
   // Roots of the transaction tree.
+  // Each element must be a valid LedgerString (as describe in ``value.proto``).
   // Required
   repeated string root_event_ids = 8;
 
@@ -71,18 +76,22 @@ message TreeEvent {
 message Transaction {
 
   // Assigned by the server. Useful for correlating logs.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Required
   string transaction_id = 1;
 
   // The ID of the command which resulted in this transaction. Missing for everyone except the submitting party.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Optional
   string command_id = 2;
 
   // The workflow ID used in command submission.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Optional
   string workflow_id = 3;
 
   // Ledger effective time.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Required
   google.protobuf.Timestamp effective_at = 4;
 

ledger-api/grpc-definitions/com/digitalasset/ledger/api/v1/transaction_filter.proto

@@ -18,6 +18,7 @@ message TransactionFilter {
   // Keys of the map determine which parties' on-ledger transactions are being queried.
   // Values of the map determine which events are disclosed in the stream per party.
   // At the minimum, a party needs to set an empty Filters message to receive any events.
+  // Each key must be a valid PartyIdString (as described in ``value.proto``).
   // Required
   map<string, Filters> filters_by_party = 1;
 }

ledger-api/grpc-definitions/com/digitalasset/ledger/api/v1/transaction_service.proto

@@ -50,6 +50,7 @@ service TransactionService {
 message GetTransactionsRequest {
 
   // Must correspond to the ledger ID reported by the Ledger Identification Service.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Required
   string ledger_id = 1;
 
@@ -89,15 +90,18 @@ message GetTransactionTreesResponse {
 
 message GetTransactionByEventIdRequest {
   // Must correspond to the ledger ID reported by the Ledger Identification Service.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Required
   string ledger_id = 1;
 
   // The ID of a particular event.
+  // Must be a valid LedgerString (as described in ``value.proto``).
   // Required
   string event_id = 2;
 
   // The parties whose events the client expects to see.
   // Events that are not visible for the parties in this collection will not be present in the response.
+  // Each element must be a valid PartyIdString (as described in ``value.proto``).
   // Required
   repeated string requesting_parties = 3;
 
@@ -109,15 +113,18 @@ message GetTransactionByEventIdRequest {
 
 message GetTransactionByIdRequest {
   // Must correspond to the ledger ID reported by the Ledger Identification Service.
+  // Must be a valid LedgerString (as describe in ``value.proto``).
   // Required
   string ledger_id = 1;
 
   // The ID of a particular transaction.
+  // Must be a valid LedgerString (as describe in ``value.proto``).
   // Required
   string transaction_id = 2;
 
   // The parties whose events the client expects to see.
   // Events that are not visible for the parties in this collection will not be present in the response.
+  // Each element be a valid PartyIdString (as describe in ``value.proto``).
   // Required
   repeated string requesting_parties = 3;
 
@@ -137,6 +144,7 @@ message GetFlatTransactionResponse {
 
 message GetLedgerEndRequest {
   // Must correspond to the ledger ID reported by the Ledger Identification Service.
+  // Must be a valid LedgerString (as describe in ``value.proto``).
   // Required
   string ledger_id = 1;
 

ledger-api/grpc-definitions/com/digitalasset/ledger/api/v1/value.proto

@@ -14,6 +14,14 @@ option java_outer_classname = "ValueOuterClass";
 option java_package = "com.digitalasset.ledger.api.v1";
 
 // Encodes values that the ledger accepts as command arguments and emits as contract arguments.
+//
+// The values encoding use different four classes of strings as identifiers. Those classes are
+// defined as follow:
+// - NameStrings are strings that match the regexp ``[A-Za-z\$_][A-Za-z0-9\$_]*``.
+// - PackageIdStrings are strings that match the regexp ``[A-Za-z0-9\-_ ]+``.
+// - PartyIdStrings are strings that match the regexp ``[A-Za-z0-9:\-_ ]+``.
+// - LedgerStrings are strings that match the regexp ``[A-Za-z0-9#:\-_ ]+``.
+//
 message Value {
   oneof Sum {
 
@@ -22,9 +30,10 @@ message Value {
     Variant variant = 2;
 
     // Identifier of an on-ledger contract. Commands which reference an unknown or already archived contract ID will fail.
+    // Must be a valid LedgerString.
     string contract_id = 3;
 
-    // Represents a homogenous list of values.
+    // Represents a homogeneous list of values.
     List list = 4;
 
     sint64 int64 = 5 [jstype = JS_STRING];
@@ -47,6 +56,7 @@ message Value {
     sfixed64 timestamp = 9 [jstype = JS_STRING];
 
     // An agent operating on the ledger.
+    // Must be a valid PartyIdString.
     string party = 11;
 
     // True or false.
@@ -90,6 +100,7 @@ message RecordField {
   // When submitting a commmand, it's optional:
   //   - if all keys within a single record are present, the order in which fields appear does not matter. however, each key must appear exactly once.
   //   - if any of the keys within a single record are omitted, the order of fields MUST match the order of declaration in the DAML template.
+  // Must be a valid NameString
   string label = 1;
 
   // A nested value of a record.
@@ -101,6 +112,7 @@ message RecordField {
 message Identifier {
 
   // The identifier of the DAML package that contains the entity.
+  // Must be a valid PackageIdString.
   // Required
   string package_id = 1;
 
@@ -126,6 +138,7 @@ message Variant {
   Identifier variant_id = 1;
 
   // Determines which of the Variant's alternatives is encoded in this message.
+  // Must be a valid NameString.
   // Required
   string constructor = 2;
 
@@ -142,6 +155,7 @@ message Enum {
   Identifier enum_id = 1;
 
   // Determines which of the Variant's alternatives is encoded in this message.
+  // Must be a valid NameString.
   // Required
   string constructor = 2;
 }