From 7c3c591a0ca2425117a0ef4eb13bb04997d5d469 Mon Sep 17 00:00:00 2001
From: Luanne Misquitta <luanne.coutinho@gmail.com>
Date: Mon, 1 Feb 2016 11:46:53 +0530
Subject: [PATCH] DATAGRAPH-765 - Document fix ambiguous mappings.

---
 src/main/asciidoc/reference/preface.adoc               |  2 +-
 .../reference/programming-model/relationships.adoc     | 10 ++++++++++
 2 files changed, 11 insertions(+), 1 deletion(-)

diff --git a/src/main/asciidoc/reference/preface.adoc b/src/main/asciidoc/reference/preface.adoc
index e5d0bacdf..551d844fa 100644
--- a/src/main/asciidoc/reference/preface.adoc
+++ b/src/main/asciidoc/reference/preface.adoc
@@ -55,7 +55,7 @@ In keeping with the Spring Data ethos, an operations interface is used to define
 
 == Mapping Strategies
 Because Neo4j is a schema-free database, Spring Data Neo4j uses a simple mechanism to map Java types to Neo4j nodes using labels.
-How that works is explained here: <<reference_programming_model_typerepresentationstrategy,Entity Type Representation>>.
+How that works is explained here: <<reference_programming-model_simple-mapping,Simplified Object Graph Mapping>>.
 
 == Transactional Support
 Neo4j uses transactions to guarantee the integrity of your data and Spring Data Neo4j supports this fully. 
diff --git a/src/main/asciidoc/reference/programming-model/relationships.adoc b/src/main/asciidoc/reference/programming-model/relationships.adoc
index 7d2a80cab..f21b65547 100644
--- a/src/main/asciidoc/reference/programming-model/relationships.adoc
+++ b/src/main/asciidoc/reference/programming-model/relationships.adoc
@@ -151,3 +151,13 @@ Thanks to changes in the underlying object-graph mapping mechanism, this is no l
 
 However, please be aware that this will only work because the end node types (Car and Pet) are different types.
 If you wanted a person to own two cars, for example, then you'd have to use a `Collection` of cars or use differently-named relationship types.
+
+[[reference_programming_model_relationships_ambiguity]]
+== Ambiguity in relationships
+
+In cases where the relationship mappings could be ambiguous, the recommendation is that
+
+* the objects be navigable in both directions and
+* the @Relationship annotations are explicit. This means if the entity has setter methods, they must be annotated
+
+Examples of ambiguous relationship mappings are multiple relationship types that resolve to the same types of entities, in a given direction, but whose domain objects are not navigable in both directions.