1// Protocol Buffers - Google's data interchange format
2// Copyright 2008 Google Inc.  All rights reserved.
3// https://developers.google.com/protocol-buffers/
4//
5// Redistribution and use in source and binary forms, with or without
6// modification, are permitted provided that the following conditions are
7// met:
8//
9//     * Redistributions of source code must retain the above copyright
10// notice, this list of conditions and the following disclaimer.
11//     * Redistributions in binary form must reproduce the above
12// copyright notice, this list of conditions and the following disclaimer
13// in the documentation and/or other materials provided with the
14// distribution.
15//     * Neither the name of Google Inc. nor the names of its
16// contributors may be used to endorse or promote products derived from
17// this software without specific prior written permission.
18//
19// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
21// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
22// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
23// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
24// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
25// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
26// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
27// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
28// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
29// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30
31syntax = "proto3";
32package conformance;
33option java_package = "com.google.protobuf.conformance";
34
35// This defines the conformance testing protocol.  This protocol exists between
36// the conformance test suite itself and the code being tested.  For each test,
37// the suite will send a ConformanceRequest message and expect a
38// ConformanceResponse message.
39//
40// You can either run the tests in two different ways:
41//
42//   1. in-process (using the interface in conformance_test.h).
43//
44//   2. as a sub-process communicating over a pipe.  Information about how to
45//      do this is in conformance_test_runner.cc.
46//
47// Pros/cons of the two approaches:
48//
49//   - running as a sub-process is much simpler for languages other than C/C++.
50//
51//   - running as a sub-process may be more tricky in unusual environments like
52//     iOS apps, where fork/stdin/stdout are not available.
53
54enum WireFormat {
55  UNSPECIFIED = 0;
56  PROTOBUF = 1;
57  JSON = 2;
58  JSPB = 3;  // Google internal only. Opensource testees just skip it.
59  TEXT_FORMAT = 4;
60}
61
62enum TestCategory {
63  UNSPECIFIED_TEST = 0;
64  BINARY_TEST = 1;  // Test binary wire format.
65  JSON_TEST = 2;    // Test json wire format.
66  // Similar to JSON_TEST. However, during parsing json, testee should ignore
67  // unknown fields. This feature is optional. Each implementation can descide
68  // whether to support it.  See
69  // https://developers.google.com/protocol-buffers/docs/proto3#json_options
70  // for more detail.
71  JSON_IGNORE_UNKNOWN_PARSING_TEST = 3;
72  // Test jspb wire format. Google internal only. Opensource testees just skip it.
73  JSPB_TEST = 4;
74  // Test text format. For cpp, java and python, testees can already deal with
75  // this type. Testees of other languages can simply skip it.
76  TEXT_FORMAT_TEST = 5;
77}
78
79// The conformance runner will request a list of failures as the first request.
80// This will be known by message_type == "conformance.FailureSet", a conformance
81// test should return a serialized FailureSet in protobuf_payload.
82message FailureSet {
83  repeated string failure = 1;
84}
85
86// Represents a single test case's input.  The testee should:
87//
88//   1. parse this proto (which should always succeed)
89//   2. parse the protobuf or JSON payload in "payload" (which may fail)
90//   3. if the parse succeeded, serialize the message in the requested format.
91message ConformanceRequest {
92  // The payload (whether protobuf of JSON) is always for a
93  // protobuf_test_messages.proto3.TestAllTypes proto (as defined in
94  // src/google/protobuf/proto3_test_messages.proto).
95  //
96  // TODO(haberman): if/when we expand the conformance tests to support proto2,
97  // we will want to include a field that lets the payload/response be a
98  // protobuf_test_messages.proto2.TestAllTypes message instead.
99  oneof payload {
100    bytes protobuf_payload = 1;
101    string json_payload = 2;
102    // Google internal only.  Opensource testees just skip it.
103    string jspb_payload = 7;
104    string text_payload = 8;
105  }
106
107  // Which format should the testee serialize its message to?
108  WireFormat requested_output_format = 3;
109
110  // The full name for the test message to use; for the moment, either:
111  // protobuf_test_messages.proto3.TestAllTypesProto3 or
112  // protobuf_test_messages.proto2.TestAllTypesProto2.
113  string message_type = 4;
114
115  // Each test is given a specific test category. Some category may need
116  // spedific support in testee programs. Refer to the defintion of TestCategory
117  // for more information.
118  TestCategory test_category = 5;
119
120  // Specify details for how to encode jspb.
121  JspbEncodingConfig jspb_encoding_options = 6;
122
123  // This can be used in json and text format. If true, testee should print
124  // unknown fields instead of ignore. This feature is optional.
125  bool print_unknown_fields = 9;
126}
127
128// Represents a single test case's output.
129message ConformanceResponse {
130  oneof result {
131    // This string should be set to indicate parsing failed.  The string can
132    // provide more information about the parse error if it is available.
133    //
134    // Setting this string does not necessarily mean the testee failed the
135    // test.  Some of the test cases are intentionally invalid input.
136    string parse_error = 1;
137
138    // If the input was successfully parsed but errors occurred when
139    // serializing it to the requested output format, set the error message in
140    // this field.
141    string serialize_error = 6;
142
143    // This should be set if some other error occurred.  This will always
144    // indicate that the test failed.  The string can provide more information
145    // about the failure.
146    string runtime_error = 2;
147
148    // If the input was successfully parsed and the requested output was
149    // protobuf, serialize it to protobuf and set it in this field.
150    bytes protobuf_payload = 3;
151
152    // If the input was successfully parsed and the requested output was JSON,
153    // serialize to JSON and set it in this field.
154    string json_payload = 4;
155
156    // For when the testee skipped the test, likely because a certain feature
157    // wasn't supported, like JSON input/output.
158    string skipped = 5;
159
160    // If the input was successfully parsed and the requested output was JSPB,
161    // serialize to JSPB and set it in this field. JSPB is google internal only
162    // format. Opensource testees can just skip it.
163    string jspb_payload = 7;
164
165    // If the input was successfully parsed and the requested output was
166    // TEXT_FORMAT, serialize to TEXT_FORMAT and set it in this field.
167    string text_payload = 8;
168  }
169}
170
171// Encoding options for jspb format.
172message JspbEncodingConfig {
173  // Encode the value field of Any as jspb array if ture, otherwise binary.
174  bool use_jspb_array_any_format = 1;
175}
176
177