1// Defines the text format for including per-op API definition and
2// overrides for client language op code generators.
3
4syntax = "proto3";
5
6package tensorflow;
7option cc_enable_arenas = true;
8option java_outer_classname = "ApiDefProtos";
9option java_multiple_files = true;
10option java_package = "org.tensorflow.framework";
11import "tensorflow/core/framework/attr_value.proto";
12
13// Used to specify and override the default API & behavior in the
14// generated code for client languages, from what you would get from
15// the OpDef alone. There will be a set of ApiDefs that are common
16// to all client languages, and another set per client language.
17// The per-client-language ApiDefs will inherit values from the
18// common ApiDefs which it can either replace or modify.
19//
20// We separate the API definition from the OpDef so we can evolve the
21// API while remaining backwards compatible when interpretting old
22// graphs.  Overrides go in an "api_def.pbtxt" file with a text-format
23// ApiDefs message.
24//
25// WARNING: Be *very* careful changing the API for any existing op --
26// you can change the semantics of existing code.  These changes may
27// need to wait until a major release of TensorFlow to avoid breaking
28// our compatibility promises.
29message ApiDef {
30  // Name of the op (in the OpDef) to specify the API for.
31  string graph_op_name = 1;
32
33  enum Visibility {
34    // Normally this is "VISIBLE" unless you are inheriting a
35    // different value from another ApiDef.
36    DEFAULT_VISIBILITY = 0;
37    // Publicly visible in the API.
38    VISIBLE = 1;
39    // Do not include this op in the generated API. If visibility is
40    // set to 'SKIP', other fields are ignored for this op.
41    SKIP = 2;
42    // Hide this op by putting it into an internal namespace (or whatever
43    // is appropriate in the target language).
44    HIDDEN = 3;
45  }
46  Visibility visibility = 2;
47
48  // If you specify any endpoint, this will replace all of the
49  // inherited endpoints.  The first endpoint should be the
50  // "canonical" endpoint, and should not be deprecated (unless all
51  // endpoints are deprecated).
52  message Endpoint {
53    // Name should be either like "CamelCaseName" or
54    // "Package.CamelCaseName". Client-language-specific ApiDefs may
55    // use a snake_case convention instead of CamelCase.
56    string name = 1;
57
58    // First GraphDef version at which the op is disallowed.
59    int32 deprecation_version = 2;
60  }
61  repeated Endpoint endpoint = 3;
62
63  message Arg {
64    string name = 1;
65
66    // Change the name used to access this arg in the API from what
67    // is used in the GraphDef.  Note that these names in `backticks`
68    // will also be replaced in the summary & description fields.
69    string rename_to = 2;
70
71    // Note: this will replace any inherited arg doc. There is no
72    // current way of modifying arg descriptions (other than replacing
73    // them entirely) as can be done with op descriptions.
74    string description = 3;
75  }
76  repeated Arg in_arg = 4;
77  repeated Arg out_arg = 5;
78  // List of original in_arg names to specify new argument order.
79  // Length of arg_order should be either empty to keep current order
80  // or match size of in_arg.
81  repeated string arg_order = 11;
82
83  // Description of the graph-construction-time configuration of this
84  // Op.  That is to say, this describes the attr fields that will
85  // be specified in the NodeDef.
86  message Attr {
87    string name = 1;
88
89    // Change the name used to access this attr in the API from what
90    // is used in the GraphDef.  Note that these names in `backticks`
91    // will also be replaced in the summary & description fields.
92    string rename_to = 2;
93
94    // Specify a new default value to use for this attr.  This default
95    // will be used when creating new graphs, as opposed to the
96    // default in the OpDef, which will be used when interpreting old
97    // GraphDefs.
98    AttrValue default_value = 3;
99
100    // Note: this will replace any inherited attr doc, there is no current
101    // way of modifying attr descriptions as can be done with op descriptions.
102    string description = 4;
103  }
104  repeated Attr attr = 6;
105
106  // One-line human-readable description of what the Op does.
107  string summary = 7;
108
109  // Additional, longer human-readable description of what the Op does.
110  string description = 8;
111
112  // Modify an existing/inherited description by adding text to the beginning
113  // or end.
114  string description_prefix = 9;
115  string description_suffix = 10;
116}
117
118message ApiDefs {
119  repeated ApiDef op = 1;
120}
121