Repository files navigation

This repository is a home for theprotocol buffer types which arecommon dependencies throughout the Google API ecosystem, and which are madeavailable for use as dependencies elsewhere.

Protocol buffers are Google's language-neutral, platform-neutral,extensible mechanism for serializing structured data – think XML,but smaller, faster, and simpler. You define how you want your data to bestructured once, then you can use special generated source code to easilywrite and read your structured data to and from a variety of data streamsand using a variety of languages.

One popular use for protocol buffers, both within Google and elsewhere,is for specifying API design. They serve as a useful representation forAPI serivices, methods, and fields. You can read more about API designphilosophy with protocol buffers by consulting ourAPI Design Guide.

When writing protocol buffers, it is common to need to reuse common patterns.For example, common types show up in many different APIs, but havea consistent implementation. The same is true elsewhere.

This repository seeks to be a home for such types; protocol buffer authorsmay check out this repository and import them into their own work to saveeffort.

The protos in the various subdirectories in this repository have differentpurposes, and are documented in their respective README files.

NOTE The protos in this repository are not updated automatically and may beoutdated. Please look to theprotos in googleapis/googleapis insteadwhich are updated regularly.

These protos are made available under an Apache license (seeLICENSE) andyou are free to depend on them within your applications. They areconsidered stable and will not change in backwards-incompaible ways.

In order to depend on these protos, use proto import statements thatreference the base of this repository, for example:

syntax="proto3";import"google/type/color.proto";// A message representing a paint can.messagePaintCan {// The size of the paint can, in gallons.floatsize_gallons=1;// The color of the paint.google.type.Colorcolor=2;}

If you are usingprotoc (or other similar tooling) to compile theseprotos yourself, you will likely require a local copy. Clone this repositoryto a convenient location and use--proto_path to specify theroot ofthis repository on your machine to the compiler.

Additionally, if using these common protos, it is not necessary to shipthe compiled types yourself in many common languages. Google providesa common protos package in several languages, which can be added as adependency, and which makes these types available.

• C#:Google.Api.CommonProtos
• Java:proto-google-common-protos
• Go:google.golang.org/genproto/googleapis
• Node.js:google-proto-files
• PHP:gax-php
• Python:googleapis-common-protos
• Ruby:googleapis-common-protos

Note that if using these packages, you will still need a local copy ofthese protos when usingprotoc, but you willnot need to ship compiledversions of them. (This is consistent withprotoc's default behavior ofonly providing compiled output for the files specifically requested, and nottheir imports.)

There are a small number of types that areso common that they areincluded in the actual protocol buffers runtime itself.These are anything with an import path beginning withgoogle/protobuf/,and notably includes timestamps and durations.

These arenot defined in this directory, and you donot need to followany of the instructions for including this (as discussed in the rootREADMEfile) if you want to use those. They are part of protocol buffers, andan import of those will "just work". These are colloquially referred toas "well-known types".

These protos are made available by Google, but are not considered to be anofficial Google product.

These protos are licensed using the Apache 2.0 software license, a permissive,copyfree license. You are free to use them in your applications providedthe license terms are honored.