diff --git a/doc/service_config.md b/doc/service_config.md index 928f27bcd80..c7c45195edf 100644 --- a/doc/service_config.md +++ b/doc/service_config.md @@ -8,12 +8,38 @@ parameters to be automatically used by all clients of their service. # Format -The format of the service config is defined by the +The fields of the service config are defined by the [`grpc.service_config.ServiceConfig` protocol buffer message](https://github.com/grpc/grpc-proto/blob/master/grpc/service_config/service_config.proto). Note that new fields may be added in the future as new functionality is introduced. +Internally, gRPC uses the service config in JSON form. The JSON +representation is the result of converting the protobuf form into JSON +using the normal [protobuf to JSON translation +rules](https://developers.google.com/protocol-buffers/docs/proto3#json). +In particular, this means: +- Field names are converted from `snake_case` to `camelCase`. +- Field values are converted as per the documented translation rules: + - Strings, 32-bit integers, and bools are converted into the + corresponding JSON types. + - 64-bit integers are converted into strings (e.g., `"251"`). + - The value of a repeated field will be represented as a JSON array. + - The value of a `google.protobuf.Duration` will be represented as a + string containing a decimal number of seconds (e.g., `"1.000340012s"`). + +For more details, see the protobuf docs linked above. + +Note that the JSON representation has one advantage over the protobuf +representation, which is that it is possible to encode configurations +for [LB policies](load-balancing.md) that are not known to gRPC. In +protobuf form, the `loadBalancingConfig` field contains a `oneof` +supporting only the built-in LB policies. However, in JSON form, the +field inside the `oneof` is encoded as a string that indicates the LB +policy name. In JSON form, that string can be any arbitrary value, not +just one of the supported policies inside of the `oneof`, so third-party +policies can be selected. + # Architecture A service config is associated with a server name. The [name @@ -23,11 +49,10 @@ name, will return both the resolved addresses and the service config. The name resolver returns the service config to the gRPC client in JSON form. Individual resolver implementations determine where and in what format the service config is stored. If the resolver implemention obtains the -service config in protobuf form, it must convert it to JSON using the -normal [protobuf to JSON translation -rules](https://developers.google.com/protocol-buffers/docs/proto3#json). +service config in protobuf form, it must convert it to JSON. Alternatively, a resolver implementation may obtain the service config -already in JSON form, in which case it may return it directly. +already in JSON form, in which case it may return it directly. Or it +may construct the JSON dynamically from some other source data. For details of how the DNS resolver plugin supports service configs, see [gRFC A2: Service Config via