Add IO Reference docs

IO Reference docs provide more details and samples for GraphML, Gryo and 


Branch: refs/heads/master
Commit: 17449e22e42c891b5e6007e200a665dbf5730872
Parents: c1206f0
Author: Stephen Mallette <>
Authored: Tue Oct 4 12:19:39 2016 -0400
Committer: Stephen Mallette <>
Committed: Thu Oct 6 14:07:44 2016 -0400

 CHANGELOG.asciidoc                              |    1 +
 docs/src/dev/io/graphml.asciidoc                |  119 +
 docs/src/dev/io/graphson.asciidoc               | 4586 ++++++++++++++++++
 docs/src/dev/io/gryo.asciidoc                   |   63 +
 docs/src/dev/io/index.asciidoc                  |   37 +
 docs/src/dev/provider/index.asciidoc            |    4 +
 docs/src/index.asciidoc                         |    2 +
 .../upgrade/release-3.2.x-incubating.asciidoc   |    9 +
 docs/static/images/gremlin-io2.png              |  Bin 0 -> 185756 bytes
 .../structure/io/graphson/   |    2 +-
 pom.xml                                         |   25 +
 .../structure/         |    2 +-
 12 files changed, 4848 insertions(+), 2 deletions(-)
diff --git a/CHANGELOG.asciidoc b/CHANGELOG.asciidoc
index 6826ca8..cfe2bfe 100644
--- a/CHANGELOG.asciidoc
+++ b/CHANGELOG.asciidoc
@@ -57,6 +57,7 @@ TinkerPop 3.2.3 (Release Date: NOT OFFICIALLY RELEASED YET)
 * `SubgraphStrategy` now supports vertex property filtering.
 * Fixed a bug in Gremlin-Python `P` where predicates reversed the order of the 
 * Added tests to `DedupTest` for the `dedup(Scope, String...)` overload.
+* Added more detailed reference documentation for IO formats.
 * Fixed a bug in serialization of `Lambda` instances in GraphSON, which 
prevented their use in remote traversals.
 * Fixed a naming bug in Gremlin-Python where `P._and` and `P._or` should be 
`P.and_` and `P.or_`. (*breaking*)
 * `where()` predicate-based steps now support `by()`-modulation.
diff --git a/docs/src/dev/io/graphml.asciidoc b/docs/src/dev/io/graphml.asciidoc
new file mode 100644
index 0000000..89eb0da
--- /dev/null
+++ b/docs/src/dev/io/graphml.asciidoc
@@ -0,0 +1,119 @@
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements.  See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You 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
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+See the License for the specific language governing permissions and
+limitations under the License.
+image:gremlin-graphml.png[width=350,float=left] The 
link:[GraphML] file format is a
+common XML-based representation of a graph. It uses an edge list format where 
vertices and their properties are listed
+and edges and their properties are listed by referencing the in and out 
vertices for each edge. GraphML does support a
+number of features which are not implemented by TinkerPop (e.g. extending 
GraphML with custom types) and there are
+features of TinkerPop that are not supported by GraphML (e.g. 
meta-properties), but GraphML does represent the most
+universal way to consume or produce a graph for integration with other systems 
as GraphML tends to have fairly wide
+In TinkerPop, GraphML is also not extended for purpose of serializing just any 
type (i.e. serialize just a `Vertex` to
+XML). It is only supported for a `Graph` instance.
+The following example is a representation of the Modern toy graph in GraphML:
+<?xml version="1.0" encoding="UTF-8"?>
+<graphml xmlns=""; 
+  <key id="labelV" for="node""labelV" attr.type="string" />
+  <key id="name" for="node""name" attr.type="string" />
+  <key id="lang" for="node""lang" attr.type="string" />
+  <key id="age" for="node""age" attr.type="int" />
+  <key id="labelE" for="edge""labelE" attr.type="string" />
+  <key id="weight" for="edge""weight" attr.type="double" />
+  <graph id="G" edgedefault="directed">
+    <node id="1">
+      <data key="labelV">person</data>
+      <data key="name">marko</data>
+      <data key="age">29</data>
+    </node>
+    <node id="2">
+      <data key="labelV">person</data>
+      <data key="name">vadas</data>
+      <data key="age">27</data>
+    </node>
+    <node id="3">
+      <data key="labelV">software</data>
+      <data key="name">lop</data>
+      <data key="lang">java</data>
+    </node>
+    <node id="4">
+      <data key="labelV">person</data>
+      <data key="name">josh</data>
+      <data key="age">32</data>
+    </node>
+    <node id="5">
+      <data key="labelV">software</data>
+      <data key="name">ripple</data>
+      <data key="lang">java</data>
+    </node>
+    <node id="6">
+      <data key="labelV">person</data>
+      <data key="name">peter</data>
+      <data key="age">35</data>
+    </node>
+    <edge id="7" source="1" target="2">
+      <data key="labelE">knows</data>
+      <data key="weight">0.5</data>
+    </edge>
+    <edge id="8" source="1" target="4">
+      <data key="labelE">knows</data>
+      <data key="weight">1.0</data>
+    </edge>
+    <edge id="9" source="1" target="3">
+      <data key="labelE">created</data>
+      <data key="weight">0.4</data>
+    </edge>
+    <edge id="10" source="4" target="5">
+      <data key="labelE">created</data>
+      <data key="weight">1.0</data>
+    </edge>
+    <edge id="11" source="4" target="3">
+      <data key="labelE">created</data>
+      <data key="weight">0.4</data>
+    </edge>
+    <edge id="12" source="6" target="3">
+      <data key="labelE">created</data>
+      <data key="weight">0.2</data>
+    </edge>
+  </graph>
+Consider the following points when reading a GraphML file to TinkerPop that 
was generated outside of TinkerPop:
+* Supports the following values in `attr.type`:
+** `string`
+** `float`
+** `double`
+** `int`
+** `long`
+** `boolean`
+* Does not currently support the `<default>` tag in the schema definitions.
+* The GraphML will be read as a directed graph regardless of the value 
supplied `edgedefault` setting in the `<graph>`
+tag as that is the nature of the type of graph that TinkerPop supports.
+* The vertex and edge `id` values will always be treated as a `String` if the 
`Graph` instance consuming the data
+supports user-supplied identifiers (i.e. TinkerGraph).
+* By default the labels for vertex and edges are referred to as "labelV" and 
"labelE" respectively. It is possible to
+change these defaults on the `Builder` for the `GraphReader`. If no label is 
supplied, the reader will default to
+"vertex" and "edge" respectively as is the general expectation in TinkerPop 
when those values are omitted.
\ No newline at end of file

Reply via email to