.proto to JSON request template

Worked example

An order service with a nested message, a map, an enum, a Timestamp and a oneof:

syntax = "proto3";
package shop.v1;

import "google/protobuf/timestamp.proto";

service Orders {
  rpc CreateOrder(CreateOrderRequest) returns (Order);
}

message CreateOrderRequest {
  string customer_id = 1;
  repeated LineItem items = 2;
  map<string, string> labels = 3;
  google.protobuf.Timestamp deliver_by = 4;
  Priority priority = 5;
  int64 budget_cents = 6;
  oneof payment {
    string card_token = 7;
    string voucher_code = 8;
  }

  message LineItem {
    string sku = 1;
    uint32 quantity = 2;
  }
}

enum Priority {
  PRIORITY_UNSPECIFIED = 0;
  PRIORITY_EXPRESS = 1;
}

message Order {
  string id = 1;
}

The template for CreateOrder's request:

{
  "customerId": "",
  "items": [
    {
      "sku": "",
      "quantity": 0
    }
  ],
  "labels": {
    "key": ""
  },
  "deliverBy": "1970-01-01T00:00:00Z",
  "priority": "PRIORITY_UNSPECIFIED",
  "budgetCents": "0",
  "cardToken": ""
}

How each field is written

• Names become lowerCamelCase (customer_id is customerId) unless the field sets json_name.
• int64 and the other 64-bit types are strings, "0", because JSON numbers lose precision past 2^53. Servers accept plain numbers too.
• An enum is the name of its first value, which in proto3 is the zero value.
• A repeated field holds one example element, and a map one example entry, so you can see their shape.
• Only the first member of each oneof is included, because sending two is an error.
• Timestamp, Duration, wrappers and the other well-known types take their JSON forms; see the well-known types reference.
• A message that contains itself stops at {}. A type from a file you did not paste is also {}, and the tool names it.
• In proto2 files, [default = …] values are used.