Add domain id for links (eiffel-community#269)

To make cross-domain links unambiguous and make it easier and more performant to locate the target events of such links we introduce a domainId member to the link object. This is a backwards-compatible change since the absence of the new member means that the target event can be assumed to exist in the same domain as the source event. Since we're now using the domain term in another place apart from the description of meta.source.domainId in each event we centralize the definition in a new glossary term.
magnusbaeck · Sep 20, 2021 · f5f82c7 · f5f82c7
1 parent 6ffca23
commit f5f82c7
Show file tree

Hide file tree

Showing 48 changed files with 4,930 additions and 57 deletions.
diff --git a/eiffel-syntax-and-usage/glossary.md b/eiffel-syntax-and-usage/glossary.md
@@ -1,5 +1,5 @@
 <!---
-   Copyright 2020 Ericsson AB.
+   Copyright 2020-2021 Ericsson AB and others.
    For a full list of individual contributors, please see the commit history.
 
    Licensed under the Apache License, Version 2.0 (the "License");
@@ -76,6 +76,12 @@ Confidence levels frequently figure in automated delivery interfaces within a ti
 #### Examples of events related to confidence levels:
 - [EiffelConfidenceLevelModifiedEvent](../eiffel-vocabulary/EiffelConfidenceLevelModifiedEvent.md)
 
+### Domain
+
+An Eiffel _domain_ is an infrastructure topological concept, which may or may not correspond to an organization or product structure. A good example would be Java packages notation, ex. com.mycompany.product.component or mycompany.site.division. Domains can be used to implement Eiffel namespaces when different companies, business units, or similar exchange Eiffel events. An Eiffel event may include a member that specifies the event's domain association.
+
+Also, keep in mind that all names are more or less prone to change. Particularly, it is recommended to avoid organizational names or site names, as organizations tend to be volatile and development is easily relocated. Relatively speaking, product and component names tend to be more stable and are therefore encouraged, while code names may be an option. You need to decide what is the most sensible option in your case.
+
 ### Environment
 An Eiffel _environment_ defines the environment in which an [activity](#activity) is executed. Could be for example a host, node, service name/uri, a Docker image or some other kind of machine configuration definition.
 

diff --git a/eiffel-syntax-and-usage/the-links-object.md b/eiffel-syntax-and-usage/the-links-object.md
@@ -1,5 +1,5 @@
 <!---
-   Copyright 2017-2018 Ericsson AB.
+   Copyright 2017-2021 Ericsson AB and others.
    For a full list of individual contributors, please see the commit history.
 
    Licensed under the Apache License, Version 2.0 (the "License");
@@ -16,15 +16,35 @@
 --->
 
 # The Links Object
-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 occurred. 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.
+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 occurred. Each trace link is an object consisting of
+
+- a type,
+- a UUID corresponding to the __meta.id__ of the target event, on string format, and
+- optionally the id of the [domain](glossary.md#domain) where the target event was published (i.e. its __meta.source.domainId__ member). The absence of a domain id means that the target event was sent in, or can at least be retrieved from, the same domain as the current event.
 
 Some link types allow multiple trace links, whereas others only allow one.
 
 Example syntax of a simple __links__ object:
 
     "links": [
-      {"type": "CAUSE", "target": "8f3e0f94-5d11-46e7-ae02-91efa15d2329"},
-      {"type": "COMPOSITION", "target": "43ee71d2-6d91-496a-b9cf-d121ff1d1bcf"}
+      {
+        "type": "CAUSE",
+        "target": "8f3e0f94-5d11-46e7-ae02-91efa15d2329"
+      },
+      {
+        "type": "COMPOSITION",
+        "target": "43ee71d2-6d91-496a-b9cf-d121ff1d1bcf"
+      }
+    ]
+
+Example syntax of a __links__ object that references an event in another domain:
+
+    "links": [
+      {
+        "type": "CAUSE",
+        "target": "a3bf3f06-a0e0-4595-a117-3393c178eb81",
+        "domainId": "com.example"
+      }
     ]
 
 The full list of optional and required links is described in the documentation of each respective event type.
diff --git a/eiffel-vocabulary/EiffelActivityCanceledEvent.md b/eiffel-vocabulary/EiffelActivityCanceledEvent.md
@@ -1,5 +1,5 @@
 <!---
-   Copyright 2017-2018 Ericsson AB.
+   Copyright 2017-2021 Ericsson AB and others.
    For a full list of individual contributors, please see the commit history.
 
    Licensed under the Apache License, Version 2.0 (the "License");
@@ -91,7 +91,7 @@ __Description:__ A description of the source of the event. This object is primar
 __Type:__ String  
 __Format:__ Free text  
 __Required:__ No  
-__Description:__ Identifies the domain that produced an event. A domain is an infrastructure topological concept, which may or may not corresponds to an organization or product structures. A good example would be Java packages notation, ex. com.mycompany.product.component or mycompany.site.division. Also, keep in mind that all names are more or less prone to change. Particularly, it is recommended to avoid organizational names or site names, as organizations tend to be volatile and development is easily relocated. Relatively speaking, product and component names tend to be more stable and are therefore encouraged, while code names may be an option. You need to decide what is the most sensible option in your case.
+__Description:__ Identifies the [domain](../eiffel-syntax-and-usage/glossary.md#domain) that produced an event.
 
 #### meta.source.host
 __Type:__ String  
@@ -179,6 +179,7 @@ __Description:__ The number of the event within the named sequence.
 ## Version History
 | Version   | Introduced in                                          | Changes                                 |
 | --------- | ------------------------------------------------------ | --------------------------------------- |
+| 3.1.0     | Current version                                        | Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). |
 | 3.0.0     | [edition-agen](../../../tree/edition-agen)             | Improved information integrity protection | (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)) |
 | 2.0.0     | [dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelActivityCanceledEvent.md) | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) |
 | 1.1.0     | [edition-toulouse](../../../tree/edition-toulouse)     | Multiple links of type FLOW_CONTEXT allowed. |

diff --git a/eiffel-vocabulary/EiffelActivityFinishedEvent.md b/eiffel-vocabulary/EiffelActivityFinishedEvent.md
@@ -1,5 +1,5 @@
 <!---
-   Copyright 2017-2018 Ericsson AB.
+   Copyright 2017-2021 Ericsson AB and others.
    For a full list of individual contributors, please see the commit history.
 
    Licensed under the Apache License, Version 2.0 (the "License");
@@ -133,7 +133,7 @@ __Description:__ A description of the source of the event. This object is primar
 __Type:__ String  
 __Format:__ Free text  
 __Required:__ No  
-__Description:__ Identifies the domain that produced an event. A domain is an infrastructure topological concept, which may or may not corresponds to an organization or product structures. A good example would be Java packages notation, ex. com.mycompany.product.component or mycompany.site.division. Also, keep in mind that all names are more or less prone to change. Particularly, it is recommended to avoid organizational names or site names, as organizations tend to be volatile and development is easily relocated. Relatively speaking, product and component names tend to be more stable and are therefore encouraged, while code names may be an option. You need to decide what is the most sensible option in your case.
+__Description:__ Identifies the [domain](../eiffel-syntax-and-usage/glossary.md#domain) that produced an event.
 
 #### meta.source.host
 __Type:__ String  
@@ -221,6 +221,7 @@ __Description:__ The number of the event within the named sequence.
 ## Version History
 | Version   | Introduced in                                          | Changes                                 |
 | --------- | ------------------------------------------------------ | --------------------------------------- |
+| 3.2.0     | Current version                                        | Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). |
 | 3.1.0     | Current version                                        | Add `data.persistentLogs.{mediaType,tags}`.   |
 | 3.0.0     | [edition-agen](../../../tree/edition-agen)             | Improved information integrity protection | (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)) |
 | 2.0.0     | [dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelActivityFinishedEvent.md) | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) |

diff --git a/eiffel-vocabulary/EiffelActivityStartedEvent.md b/eiffel-vocabulary/EiffelActivityStartedEvent.md
@@ -1,5 +1,5 @@
 <!---
-   Copyright 2017-2018 Ericsson AB.
+   Copyright 2017-2021 Ericsson AB and others.
    For a full list of individual contributors, please see the commit history.
 
    Licensed under the Apache License, Version 2.0 (the "License");
@@ -122,7 +122,7 @@ __Description:__ A description of the source of the event. This object is primar
 __Type:__ String  
 __Format:__ Free text  
 __Required:__ No  
-__Description:__ Identifies the domain that produced an event. A domain is an infrastructure topological concept, which may or may not corresponds to an organization or product structures. A good example would be Java packages notation, ex. com.mycompany.product.component or mycompany.site.division. Also, keep in mind that all names are more or less prone to change. Particularly, it is recommended to avoid organizational names or site names, as organizations tend to be volatile and development is easily relocated. Relatively speaking, product and component names tend to be more stable and are therefore encouraged, while code names may be an option. You need to decide what is the most sensible option in your case.
+__Description:__ Identifies the [domain](../eiffel-syntax-and-usage/glossary.md#domain) that produced an event.
 
 #### meta.source.host
 __Type:__ String  
@@ -210,6 +210,7 @@ __Description:__ The number of the event within the named sequence.
 ## Version History
 | Version   | Introduced in                                          | Changes                                 |
 | --------- | ------------------------------------------------------ | --------------------------------------- |
+| 4.2.0     | Current version                                        | Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). |
 | 4.1.0     | Current version                                        | Add `data.liveLogs.{mediaType,tags}`.   |
 | 4.0.0     | [edition-agen-1](../../../tree/edition-agen-1)             | Bug fix in schema file (see [Issue 205](https://github.com/eiffel-community/eiffel/issues/205)) |
 | 3.0.0     | [edition-agen](../../../tree/edition-agen)             | Improved information integrity protection (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)) |

diff --git a/eiffel-vocabulary/EiffelActivityTriggeredEvent.md b/eiffel-vocabulary/EiffelActivityTriggeredEvent.md
@@ -1,5 +1,5 @@
 <!---
-   Copyright 2017-2018 Ericsson AB.
+   Copyright 2017-2021 Ericsson AB and others.
    For a full list of individual contributors, please see the commit history.
 
    Licensed under the Apache License, Version 2.0 (the "License");
@@ -119,7 +119,7 @@ __Description:__ A description of the source of the event. This object is primar
 __Type:__ String  
 __Format:__ Free text  
 __Required:__ No  
-__Description:__ Identifies the domain that produced an event. A domain is an infrastructure topological concept, which may or may not corresponds to an organization or product structures. A good example would be Java packages notation, ex. com.mycompany.product.component or mycompany.site.division. Also, keep in mind that all names are more or less prone to change. Particularly, it is recommended to avoid organizational names or site names, as organizations tend to be volatile and development is easily relocated. Relatively speaking, product and component names tend to be more stable and are therefore encouraged, while code names may be an option. You need to decide what is the most sensible option in your case.
+__Description:__ Identifies the [domain](../eiffel-syntax-and-usage/glossary.md#domain) that produced an event.
 
 #### meta.source.host
 __Type:__ String  
@@ -207,6 +207,7 @@ __Description:__ The number of the event within the named sequence.
 ## Version History
 | Version   | Introduced in                                          | Changes                                 |
 | --------- | ------------------------------------------------------ | --------------------------------------- |
+| 4.1.0     | Current version                                        | Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). |
 | 4.0.0     | [edition-agen-1](../../../tree/edition-agen-1)             | Bug fix in schema file (see [Issue 205](https://github.com/eiffel-community/eiffel/issues/205)) |
 | 3.0.0     | [edition-agen](../../../tree/edition-agen)             | Improved information integrity protection (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)) |
 | 2.0.0     | [dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelActivityTriggeredEvent.md) | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) |

diff --git a/eiffel-vocabulary/EiffelAnnouncementPublishedEvent.md b/eiffel-vocabulary/EiffelAnnouncementPublishedEvent.md
@@ -1,5 +1,5 @@
 <!---
-   Copyright 2017-2018 Ericsson AB.
+   Copyright 2017-2021 Ericsson AB and others.
    For a full list of individual contributors, please see the commit history.
 
    Licensed under the Apache License, Version 2.0 (the "License");
@@ -107,7 +107,7 @@ __Description:__ A description of the source of the event. This object is primar
 __Type:__ String  
 __Format:__ Free text  
 __Required:__ No  
-__Description:__ Identifies the domain that produced an event. A domain is an infrastructure topological concept, which may or may not corresponds to an organization or product structures. A good example would be Java packages notation, ex. com.mycompany.product.component or mycompany.site.division. Also, keep in mind that all names are more or less prone to change. Particularly, it is recommended to avoid organizational names or site names, as organizations tend to be volatile and development is easily relocated. Relatively speaking, product and component names tend to be more stable and are therefore encouraged, while code names may be an option. You need to decide what is the most sensible option in your case.
+__Description:__ Identifies the [domain](../eiffel-syntax-and-usage/glossary.md#domain) that produced an event.
 
 #### meta.source.host
 __Type:__ String  
@@ -195,6 +195,7 @@ __Description:__ The number of the event within the named sequence.
 ## Version History
 | Version   | Introduced in                                          | Changes                                 |
 | --------- | ------------------------------------------------------ | --------------------------------------- |
+| 3.1.0     | Current version                                        | Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). |
 | 3.0.0     | [edition-agen](../../../tree/edition-agen)             | Improved information integrity protection | (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)) |
 | 2.0.0     | [dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelAnnouncementPublishedEvent.md) | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) |
 | 1.1.0     | [edition-toulouse](../../../tree/edition-toulouse)     | Multiple links of type FLOW_CONTEXT allowed. |

diff --git a/eiffel-vocabulary/EiffelArtifactCreatedEvent.md b/eiffel-vocabulary/EiffelArtifactCreatedEvent.md
@@ -1,5 +1,5 @@
 <!---
-   Copyright 2017-2018 Ericsson AB.
+   Copyright 2017-2021 Ericsson AB and others.
    For a full list of individual contributors, please see the commit history.
 
    Licensed under the Apache License, Version 2.0 (the "License");
@@ -151,7 +151,7 @@ __Description:__ A description of the source of the event. This object is primar
 __Type:__ String  
 __Format:__ Free text  
 __Required:__ No  
-__Description:__ Identifies the domain that produced an event. A domain is an infrastructure topological concept, which may or may not corresponds to an organization or product structures. A good example would be Java packages notation, ex. com.mycompany.product.component or mycompany.site.division. Also, keep in mind that all names are more or less prone to change. Particularly, it is recommended to avoid organizational names or site names, as organizations tend to be volatile and development is easily relocated. Relatively speaking, product and component names tend to be more stable and are therefore encouraged, while code names may be an option. You need to decide what is the most sensible option in your case.
+__Description:__ Identifies the [domain](../eiffel-syntax-and-usage/glossary.md#domain) that produced an event.
 
 #### meta.source.host
 __Type:__ String  
@@ -239,6 +239,7 @@ __Description:__ The number of the event within the named sequence.
 ## Version History
 | Version   | Introduced in                                          | Changes                                 |
 | --------- | ------------------------------------------------------ | --------------------------------------- |
+| 3.1.0     | Current version                                        | Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). |
 | 3.0.0     | [edition-agen](../../../tree/edition-agen)             | Improved information integrity protection | (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)) |
 | 2.0.0     | [dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelArtifactCreatedEvent.md) | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) |
 | 1.1.0     | [edition-toulouse](../../../tree/edition-toulouse)     | Multiple links of type FLOW_CONTEXT allowed. |

diff --git a/eiffel-vocabulary/EiffelArtifactPublishedEvent.md b/eiffel-vocabulary/EiffelArtifactPublishedEvent.md
@@ -111,7 +111,7 @@ __Description:__ A description of the source of the event. This object is primar
 __Type:__ String  
 __Format:__ Free text  
 __Required:__ No  
-__Description:__ Identifies the domain that produced an event. A domain is an infrastructure topological concept, which may or may not corresponds to an organization or product structures. A good example would be Java packages notation, ex. com.mycompany.product.component or mycompany.site.division. Also, keep in mind that all names are more or less prone to change. Particularly, it is recommended to avoid organizational names or site names, as organizations tend to be volatile and development is easily relocated. Relatively speaking, product and component names tend to be more stable and are therefore encouraged, while code names may be an option. You need to decide what is the most sensible option in your case.
+__Description:__ Identifies the [domain](../eiffel-syntax-and-usage/glossary.md#domain) that produced an event.
 
 #### meta.source.host
 __Type:__ String  
@@ -199,6 +199,7 @@ __Description:__ The number of the event within the named sequence.
 ## Version History
 | Version   | Introduced in                                          | Changes                                 |
 | --------- | ------------------------------------------------------ | --------------------------------------- |
+| 3.2.0     | Current version                                        | Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)). |
 | 3.1.0     | [edition-paris](../../../tree/edition-paris)           | Added name qualifier for artifact locations (see [Issue 248](https://github.com/eiffel-community/eiffel/issues/248)) |
 | 3.0.0     | [edition-agen](../../../tree/edition-agen)             | Improved information integrity protection | (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)) |
 | 2.0.0     | [dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelArtifactPublishedEvent.md) | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) |