eiffel-community · d-stahl-ericsson · Jun 20, 2016 · Jun 15, 2016
diff --git a/eiffel-syntax-and-usage/the-links-object.md b/eiffel-syntax-and-usage/the-links-object.md
@@ -1,49 +1,55 @@
 # The Links Object
-The __links__ object contains trace links to other Eiffel events. These trace links by definition always reference backwards in time – it is only possible to reference an event that has already occured. The value is always a UUID or array of UUIDs, corresponding to the __meta.id__ of the target(s), on String (or String array) format.
+The __links__ object is an array of trace links to other Eiffel events. These trace links by definition always reference backwards in time – it is only possible to reference an event that has already occured. Each trace link is a tuple consisting of a type and a UUID corresponding to the __meta.id__ of the target event, on String format.
 
-Every trace link type has a set of possible source event types, and a set of possible target event types.
+Some link types allow multiple trace links, whereas others only allow one.
 
-## Links Members
-### links.causes
-__Type:__ String[]  
+Example syntax of a simple __links__ object:
+
+    "links": [
+      {"type": "CAUSE", "target": "8f3e0f94-5d11-46e7-ae02-91efa15d2329"},
+      {"type": "COMPOSITION", "target": "43ee71d2-6d91-496a-b9cf-d121ff1d1bcf"}
+    ]
+
+## Legal Link Types
+### CAUSE
 __Required in:__ None  
 __Optional in:__ Any  
 __Legal targets:__ Any  
-__Description:__ Identifies one or more causes of the event occurring. SHOULD not be used in conjunction with __links.context__: individual events providing __links.causes__ within a larger context gives rise to ambiguity. It is instead recommended to let the root event of the context declare __links.causes__.  
+__Multiple allowed:__ Yes  
+__Description:__ Identifies a cause of the event occurring. SHOULD not be used in conjunction with __CONTEXT__: individual events providing __CAUSE__ within a larger context gives rise to ambiguity. It is instead recommended to let the root event of the context declare __CAUSE__.  
 
-### links.context
-__Type:__ String  
+### CONTEXT
 __Required in:__ None  
 __Optional in:__ Any  
 __Legal targets:__ [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md), 
 [EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md)  
-__Description:__ Identifies a the activity or test suite of which the event constitutes a part. SHOULD not be used in conjunction with __links.causes__, see above. Note that multiple layers may be modeled using __links.context__, e.g. an activity being part of another activity.
+__Multiple allowed:__ No  
+__Description:__ Identifies a the activity or test suite of which the event constitutes a part. SHOULD not be used in conjunction with __CAUSE__, see above. Note that multiple layers may be modeled using __CONTEXT__, e.g. an activity being part of another activity.
 
-### links.flowContext
-__Type:__ String  
+### FLOW_CONTEXT
 __Required in:__ None  
 __Optional in:__ Any  
 __Legal targets:__ [EiffelFlowContextDefinedEvent](../eiffel-vocabulary/EiffelFlowContextDefinedEvent.md)  
+__Multiple allowed:__ No  
 __Description:__ Identifies the flow context of the event: which is the continuous integration and delivery flow in which this occurred – e.g. which product, project, track or version this is applicable to.
 
-### links.activityExecution
-__Type:__ String  
+### ACTIVITY_EXECUTION
 __Required in:__ [EiffelActivityCanceledEvent](../eiffel-vocabulary/EiffelActivityCanceledEvent.md), 
 [EiffelActivityStartedEvent](../eiffel-vocabulary/EiffelActivityStartedEvent.md), 
 [EiffelActivityFinishedEvent](../eiffel-vocabulary/EiffelActivityFinishedEvent.md)  
 __Optional in:__ None  
 __Legal targets:__ [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md)  
-__Description:__ Declares the activity execution the event relates to. In other words, [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md) acts as a handle for the activity execution. This differs from __links.context__. In __links.activityExecution__ the source carries information pertaining to the target (i.e. the activity started, finished or was canceled). In __links.context__, on the other hand, the source constitutes a subset of the target (e.g. this test case was executed as part of that activity or test suite).
+__Multiple allowed:__ No  
+__Description:__ Declares the activity execution the event relates to. In other words, [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md) acts as a handle for the activity execution. This differs from __CONTEXT__. In __ACTIVITY_EXECUTION__ the source carries information pertaining to the target (i.e. the activity started, finished or was canceled). In __CONTEXT__, on the other hand, the source constitutes a subset of the target (e.g. this test case was executed as part of that activity or test suite).
 
-### links.previousActivityExecution
-__Type:__ String  
+### PREVIOUS_ACTIVITY_EXECUTION
 __Required in:__ None  
 __Optional in:__ [EiffelActivityStartedEvent](../eiffel-vocabulary/EiffelActivityStartedEvent.md)  
 __Legal targets:__ [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md)  
+__Multiple allowed:__ No  
 __Description:__ Identifies the latest previous execution of the activity.
 
-### links.previousVersions
-__Type:__ String[]  
+### PREVIOUS_VERSION
 __Required in:__ None  
 __Optional in:__ [EiffelArtifactCreatedEvent](../eiffel-vocabulary/EiffelArtifactCreatedEvent.md), 
 [EiffelDocumentationCreatedEvent](../eiffel-vocabulary/EiffelDocumentationCreatedEvent.md), 
@@ -57,105 +63,106 @@ __Legal targets:__ [EiffelArtifactCreatedEvent](../eiffel-vocabulary/EiffelArtif
 [EiffelEnvironmentDefinedEvent](../eiffel-vocabulary/EiffelEnvironmentDefinedEvent.md), 
 [EiffelSourceChangeCreatedEvent](../eiffel-vocabulary/EiffelSourceChangeCreatedEvent.md), 
 [EiffelSourceChangeSubmittedEvent](../eiffel-vocabulary/EiffelSourceChangeSubmittedEvent.md)  
-__Description:__ Identifies the latest previous version(s) of the engineering artifact the event represents, e.g. the previous version of the artifact, the previous version of the composition etc. The target event type SHALL be the same as the source event type. In most cases a single element array is to be expected: multiple elements are intended for representing merges.
+__Multiple allowed:__ Yes  
+__Description:__ Identifies a latest previous version (there may be more than one in case of merges) of the engineering artifact the event represents, e.g. the previous version of the artifact, the previous version of the composition etc. The target event type SHALL be the same as the source event type.
 
-### links.composition
-__Type:__ String  
+### COMPOSITION
 __Required in:__ None  
 __Optional in:__ [EiffelArtifactCreatedEvent](../eiffel-vocabulary/EiffelArtifactCreatedEvent.md)  
 __Legal targets:__ [EiffelCompositionDefinedEvent](../eiffel-vocabulary/EiffelCompositionDefinedEvent.md)  
+__Multiple allowed:__ No  
 __Description:__ Identifies the composition from which an artifact was built.
 
-### links.environment
-__Type:__ String  
+### ENVIRONMENT
 __Required in:__ None  
 __Optional in:__ [EiffelArtifactCreatedEvent](../eiffel-vocabulary/EiffelArtifactCreatedEvent.md), 
 [EiffelArtifactTestCaseStartedEvent](../eiffel-vocabulary/EiffelArtifactTestCaseStartedEvent.md)  
 __Legal targets:__ [EiffelEnvironmentDefinedEvent](../eiffel-vocabulary/EiffelEnvironmentDefinedEvent.md)  
+__Multiple allowed:__ No  
 __Description:__ Identifies the environment in which an event occurred, e.g. in which environment an artifact was built.
 
-### links.artifact
-__Type:__ String  
+### ARTIFACT
 __Required in:__ [EiffelArtifactPublishedEvent](../eiffel-vocabulary/EiffelArtifactPublishedEvent.md)  
 __Optional in:__ None  
 __Legal targets:__ [EiffelArtifactCreatedEvent](../eiffel-vocabulary/EiffelArtifactCreatedEvent.md)  
+__Multiple allowed:__ No  
 __Description:__ Identifies the artifact that was published.
 
-### links.subjects
-__Type:__ String[]  
+### SUBJECT
 __Required in:__ [EiffelConfidenceLevelModifiedEvent](../eiffel-vocabulary/EiffelConfidenceLevelModifiedEvent.md)  
 __Optional in:__ None  
 __Legal targets:__ [EiffelCompositionDefinedEvent](../eiffel-vocabulary/EiffelCompositionDefinedEvent.md),
 [EiffelArtifactCreatedEvent](../eiffel-vocabulary/EiffelArtifactCreatedEvent.md),
 [EiffelDocumentationCreatedEvent](../eiffel-vocabulary/EiffelDocumentationCreatedEvent.md),
 [EiffelSourceChangeCreatedEvent](../eiffel-vocabulary/EiffelSourceChangeCreatedEvent.md),
 [EiffelSourceChangeSubmittedEvent](../eiffel-vocabulary/EiffelSourceChangeSubmittedEvent.md)  
-__Description:__ Identifies the subject(s) of the confidence level.
+__Multiple allowed:__ Yes  
+__Description:__ Identifies a subject of the confidence level.
 
-### links.elements
-__Type:__ String[]  
+### ELEMENT
 __Required in:__ None  
 __Optional in:__ [EiffelCompositionDefinedEvent](../eiffel-vocabulary/EiffelCompositionDefinedEvent.md)  
 __Legal targets:__ [EiffelCompositionDefinedEvent](../eiffel-vocabulary/EiffelCompositionDefinedEvent.md),
 [EiffelSourceChangeSubmittedEvent](../eiffel-vocabulary/EiffelSourceChangeSubmittedEvent.md),
 [EiffelArtifactCreatedEvent](../eiffel-vocabulary/EiffelArtifactCreatedEvent.md),
 [EiffelDocumentationCreatedEvent](../eiffel-vocabulary/EiffelDocumentationCreatedEvent.md)  
-__Description:__ Identifies elements and or sub-compositions of the composition. The latter is particularly useful for documenting large and potentially decentralized compositions, and may be used to reduce the need to repeat large compositions in which only small parts are subject to frequent change.
+__Multiple allowed:__ Yes  
+__Description:__ Identifies an element and/or sub-composition of the composition. The latter is particularly useful for documenting large and potentially decentralized compositions, and may be used to reduce the need to repeat large compositions in which only small parts are subject to frequent change.
 
-### links.base
-__Type:__ String  
+### BASE
 __Required in:__ None  
 __Optional in:__ [EiffelSourceChangeCreatedEvent](../eiffel-vocabulary/EiffelSourceChangeCreatedEvent.md)  
 __Legal targets:__ [EiffelSourceChangeSubmittedEvent](../eiffel-vocabulary/EiffelSourceChangeSubmittedEvent.md)  
+__Multiple allowed:__ No  
 __Description:__ Identifies the base revision of the proposed change.
 
-### links.change
-__Type:__ String  
+### CHANGE
 __Required in:__ None  
 __Optional in:__ [EiffelSourceChangeSubmittedEvent](../eiffel-vocabulary/EiffelSourceChangeSubmittedEvent.md)  
 __Legal targets:__ [EiffelSourceChangeCreatedEvent](../eiffel-vocabulary/EiffelSourceChangeCreatedEvent.md)  
+__Multiple allowed:__ No  
 __Description:__ Identifies the change that was submitted.
 
-### links.testSuiteExecution
-__Type:__ String  
+### TEST_SUITE_EXECUTION
 __Required in:__ [EiffelTestSuiteFinishedEvent](../eiffel-vocabulary/EiffelTestSuiteFinishedEvent.md)  
 __Optional in:__ None  
 __Legal targets:__ [EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md)  
+__Multiple allowed:__ No  
 __Description:__ Identifies the relevant test suite execution. In other words, [EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) acts as a handle for a particular test suite execution.
 
-### links.testCaseExecution
-__Type:__ String  
+### TEST_CASE_EXECUTION
 __Required in:__ [EiffelTestCaseFinishedEvent](../eiffel-vocabulary/EiffelTestCaseFinishedEvent.md)  
 __Optional in:__ None  
 __Legal targets:__ [EiffelTestCaseStartedEvent](../eiffel-vocabulary/EiffelTestCaseStartedEvent.md)  
+__Multiple allowed:__ No  
 __Description:__ Identifies the relevant test case execution. In other words, [EiffelTestCaseStartedEvent](../eiffel-vocabulary/EiffelTestCaseStartedEvent.md) acts as a handle for a particular test case execution.
 
-### links.iut
-__Type:__ String  
+### IUT
 __Required in:__ [EiffelTestCaseStartedEvent](../eiffel-vocabulary/EiffelTestCaseStartedEvent.md)  
 __Optional in:__ None  
 __Legal targets:__ [EiffelArtifactCreatedEvent](../eiffel-vocabulary/EiffelArtifactCreatedEvent.md),
 [EiffelCompositionDefinedEvent](../eiffel-vocabulary/EiffelCompositionDefinedEvent.md)  
+__Multiple allowed:__ No  
 __Description:__ Identifies the Item Under Test.
 
-### links.terc
-__Type:__ String  
+### TERC
 __Required in:__ None  
 __Optional in:__ [EiffelTestCaseStartedEvent](../eiffel-vocabulary/EiffelTestCaseStartedEvent.md)  
 __Legal targets:__ [EiffelTestExecutionRecipeCollectionCreatedEvent](../eiffel-vocabulary/EiffelTestExecutionRecipeCollectionCreatedEvent.md)  
+__Multiple allowed:__ No  
 __Description:__ Identifies the Test Execution Recipe Collection dictating the execution of the test case.
 
-### links.modifiedAnnouncement
-__Type:__ String  
+### MODIFIED_ANNOUNCEMENT
 __Required in:__ None  
 __Optional in:__ [EiffelAnnouncementEvent](../eiffel-vocabulary/EiffelAnnouncementEvent.md)  
 __Legal targets:__ [EiffelAnnouncementEvent](../eiffel-vocabulary/EiffelAnnouncementEvent.md)  
+__Multiple allowed:__ No  
 __Description:__ Identifies an announcement of which this event represents an update or modification, if any. Example usage is to declare the end to a previously announced situation.
 
-### links.subConfidenceLevels
-__Type:__ String[]  
+### SUB_CONFIDENCE_LEVEL
 __Required in:__ None  
 __Optional in:__ [EiffelConfidenceLevelModifiedEvent](../eiffel-vocabulary/EiffelConfidenceLevelModifiedEvent.md)  
 __Legal targets:__ [EiffelConfidenceLevelModifiedEvent](../eiffel-vocabulary/EiffelConfidenceLevelModifiedEvent.md)  
-__Description:__ Used in events summarizing multiple confidence levels. Example use case: the confidence level "allTestsOk" summarizes the confidence levels "unitTestsOk, "scenarioTestsOk" and "deploymentTestsOk", and consequently links to them using this field. This is intended for purely descriptive, rather than prescriptive, use.
+__Multiple allowed:__ Yes  
+__Description:__ Used in events summarizing multiple confidence levels. Example use case: the confidence level "allTestsOk" summarizes the confidence levels "unitTestsOk, "scenarioTestsOk" and "deploymentTestsOk", and consequently links to them via __SUB_CONFIDENCE_LEVEL__. This is intended for purely descriptive, rather than prescriptive, use.
 
diff --git a/eiffel-vocabulary/EiffelActivityCanceledEvent.md b/eiffel-vocabulary/EiffelActivityCanceledEvent.md
@@ -1,5 +1,5 @@
 # EiffelActivityCanceledEvent
-The EiffelActivityCanceledEvent signals that a previously triggered activity execution has been canceled _before it has started_. This is typically used in queuing situations where a queued execution is dequeued. It is recommended that __links.causes__ be used to indicate the reason.
+The EiffelActivityCanceledEvent signals that a previously triggered activity execution has been canceled _before it has started_. This is typically used in queuing situations where a queued execution is dequeued. It is recommended that __CAUSE__ links be used to indicate the reason.
 
 ## Data Members
 ### data.reason

diff --git a/eiffel-vocabulary/EiffelActivityTriggeredEvent.md b/eiffel-vocabulary/EiffelActivityTriggeredEvent.md
@@ -25,7 +25,7 @@ __Required:__ Yes
 __Legal values:__ MANUAL, EIFFEL_EVENT, SOURCE_CHANGE, TIMER, OTHER  
 __Description:__ The type of trigger.  
 MANUAL signifies that the activity was manually triggered.  
-EIFFEL_EVENT signifies that the activity was triggered by one or more Eiffel events. These events should be represented in __links.causes__.  
+EIFFEL_EVENT signifies that the activity was triggered by one or more Eiffel events. These events should be represented via __CAUSE__ links.  
 SOURCE_CHANGE signifies that the activity was triggered as a consequence of a detected source change __not__ represented by Eiffel events.  
 TIMER signifies that the activity was triggered by a timer.  
 OTHER signifies any other triggering cause.

diff --git a/eiffel-vocabulary/EiffelCompositionDefinedEvent.md b/eiffel-vocabulary/EiffelCompositionDefinedEvent.md
@@ -10,7 +10,7 @@ __Description:__ The name of the composition.
 ### data.version
 __Type:__ String  
 __Required:__ No  
-__Description:__ The version of the composition, if any. This is in a sense redundant, as relationships between compositions can be tracked via __links.previousVersions__, but can be used for improved clarity and semantics.
+__Description:__ The version of the composition, if any. This is in a sense redundant, as relationships between compositions can be tracked via the __PREVIOUS_VERSION__ link type, but can be used for improved clarity and semantics.
 
 ## Examples
 * [Simple example](https://github.com/Ericsson/eiffel-examples/blob/master/events/EiffelCompositionDefinedEvent/simple.json)
diff --git a/eiffel-vocabulary/EiffelSourceChangeSubmittedEvent.md b/eiffel-vocabulary/EiffelSourceChangeSubmittedEvent.md
@@ -1,5 +1,5 @@
 # EiffelSourceChangeSubmittedEvent
-The EiffelSourceChangeSubmittedEvent declares that a change has been integrated into to a shared source branch of interest (e.g. "master", "dev" or "mainline") as opposed to a private or local branch. Note that it does not describe what has changed, but instead uses __links.change__ to reference [EiffelSourceChangeCreatedEvent](./EiffelSourceChangeCreatedEvent.md).
+The EiffelSourceChangeSubmittedEvent declares that a change has been integrated into to a shared source branch of interest (e.g. "master", "dev" or "mainline") as opposed to a private or local branch. Note that it does not describe what has changed, but instead uses the __CHANGE__ link type to reference [EiffelSourceChangeCreatedEvent](./EiffelSourceChangeCreatedEvent.md).
 
 Typical use cases for EiffelSourceChangeSubmittedEvent is to signal that a patch has passed code review and been submitted or that a feature/topic/team branch has been merged into the mainline/trunk/master. Where changes are made directly on the mainline, it is recommended to send both [EiffelSourceChangeCreatedEvent](./EiffelSourceChangeCreatedEvent.md) and EiffelSourceChangeSubmittedEvent together for information completeness.
 

diff --git a/usage-examples/build-avoidance.gliffy b/usage-examples/build-avoidance.gliffy