// Copyright 2015 The TensorFlow Authors. All Rights Reserved.
//
// Licensed under the Apache License, Version 2.0 (the 'License');
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an 'AS IS' BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
// =============================================================================

// GraphExplorer is a tool that supports interactive, hierarchical visualization
// of graphs. GraphExplorer renders graphs generated by TensorFlow represented
// as GraphDef messages defined in tensorflow/core/framework/graph.proto. The
// GraphDef proto does not allow for explicitly specifying visual attributes of
// the graph such as color, line thickness, fonts, etc. This file introduces a
// new proto for representing graphs and specifying visual attributes of graphs.
//
// The structure of the Graph proto is given by the EBNF grammar below. Consult
// the message definitions below for details.
//
//  graph ::= node* edge* node_attribute* metanode_attribute* edge_attribute*
//            graph_attribute*
//  node  ::= node_id node_attribute* metanode_attribute* node_data*
//  edge  ::= source_id target_id edge_attribute* edge_data*
//
// A graph consists of a list of nodes and a list of edges and attributes for
// nodes, edges and the graph. Attributes have a name and a value and are
// represented as key-value pairs, with {"color", "blue"} being an example.
// Attributes have a scope, where the broadest scope is the graph and the
// narrowest is a node that has no internal structure.
syntax = "proto3";

package graph_explorer;

// There are two types of nodes. A 'metanode' contains other
// nodes and a 'leaf node' has no internal structure.  The metanode containment
// relationship is acyclic, meaning that if a metanode 'A' contains the metanode
// 'B', then 'B' cannot contain 'A'.
message Node {
  // The identifier of a node is a sequence of strings separated by '/'. The
  // identifier provides a unique name for a node and defines its hierarchical
  // relation to other nodes.  If no label is provided  the last part of the
  // identifier is used as a label.
  //
  // Example: In the graph below, metanodes are written with square brackets and
  // leaf nodes with parentheses. The metanode 'node1' contains the leaf node
  // 'node4' and the metanode 'node2', which contains the leaf node 'node3'.
  //
  //   [node1 [node2 (node3)] (node4)]
  //
  // The identifiers for these nodes are: "node1", "node1/node2",
  // "node1/node2/node3", and "node1/node4".
  string name = 1;

  // A node attribute is information used by Graph Explorer to style a node.
  map<string, string> node_attr = 2;

  // A metanode attribute is one that is inherited by all nodes inside the
  // current metanode. If an attribute applies only to the current node and
  // should not be inherited, it should be specified as a node attribute.
  map<string, string> metanode_attr = 3;
};

// An edge consists of a source and a target node, specified by their
// identifiers. An edge has attributes and data that are similar to node
// attributes and node data. Edges do not form a hierarchy so there are no
// metanode attributes.
message Edge {
  // The source and target fields must have the format of a Node name.
  string source = 1;
  string target = 2;

  // Edge attributes.
  map<string, string> edge_attr = 3;
}

message Graph {
  // List of nodes in the graph.
  repeated Node node = 1;

  // List of edges in the graph.
  repeated Edge edge = 2;

  // Default values of node, metanode and edge attributes.
  map<string, string> node_attr = 3;
  map<string, string> metanode_attr = 4;
  map<string, string> edge_attr = 5;

  // Graph attributes.
  map<string, string> graph_attr = 6;
};
