Add section on uniquely identifier interface definitions

articles/142_idl.md

@@ -40,7 +40,7 @@ Both line comments (`//`) as well as block comments (`/* ... */`) are being supp
 
 #### 7.2.3 Identifiers
 
-An identifier must start with an is an ASCII alphabetic characteran followed by any number of ASCII alphabetic, digit and underscore (`_`) characters.
+An identifier must start with an ASCII alphabetic character followed by any number of ASCII alphabetic, digit and underscore (`_`) characters.
 
 #### 7.2.6 Literals
 
@@ -129,7 +129,7 @@ the DDS-XTypes specification 1.2 defines it with 16-bit.
 | ---------------------- | ---------------------------------------------------------- |
 | sequence\<type\_spec>  | sequence of items of the specific type\_spec               |
 |                        | the sequence is unbounded and no maximum size is specified |
-| sequence<type_spec, N> | sequence of of up to N items of the specified type\_spec   |
+| sequence<type_spec, N> | sequence of up to N items of the specified type\_spec      |
 |                        | the sequence is bounded and contain between 0 and N items  |
 
 #### 7.4.1.4.4.3.2 Strings
@@ -159,6 +159,60 @@ An enumerated type consist of an ordered list of enumerators.
 A multidimensional, fixed-size array is defined by the type of each item and the explicit sizes for each dimension.
 For now only a one-dimensional, fixed-size array is supported though.
 
+### Interface Identification
+
+#### Uniform Resource Name (URN)
+
+Following 7.5.1 from the IDL 4.2 specification, every IDL definition can be uniquely identified with a qualified name of the form
+**\<scoped\_name>::\<identifier>**.
+In addition to the specification, the scope of an IDL definition is prefixed with the package name from which the defintion is derived.
+This is to guarantee uniqueness of definitions across packages (under the assumption that package names are unique).
+Therefore, each interface defintion can be resolved with a URN of the form: **\<package\_name>/\<scoped\_name>/\<identifier>**.
+
+#### Uniform Resource Locator (URL)
+
+For source code to use an interface (e.g. include or import) there needs to be a way to reference the file containing the defintion.
+To reference the location of an IDL defintion we use a URL of the form: **rosidl:<package\_name>/<subfolder>/<file>**.
+Where *<subfolder>* is the relative path from the root of the package where generated defintions can be found.
+
+#### Example
+
+Imagine we have a package `foo_pkg` containing an IDL file `Bar.idl` with the following contents:
+
+```idl
+struct MsgA {
+  boolean bool_member;
+};
+
+module bar {
+  const int8 MY_CONSTANT = 42;
+
+  struct MsgB {
+    int8 int_member;
+  };
+
+  module baz {
+    struct MsgC {
+      string string_member;
+    };
+  };
+};
+```
+
+Also imagine the message generation pipeline places the generated implementation to a subfolder `interface`.
+
+Then, we can reference the interfaces with the following URNs:
+
+- `foo_pkg/MsgA`
+- `foo_pkg/bar/MY_CONSTANT`
+- `foo_pkg/bar/MsgB`
+- `foo_pkg/bar/baz/MsgC`
+
+And all can be located with the URL: `rosidl:foo_pkg/interface/Bar`.
+
+For example, the definitions could be included in C++ with `#include <foo_pkg/interface/Bar.hpp>`
+or imported in Python with `import foo_pkg.interface.Bar`.
+
 ### Annotations
 
 The syntax for arbitrary annotations is supported.

articles/143_legacy_interface_definition.md

@@ -39,21 +39,52 @@ Each field is described by a *type* and a *name*.
 A single data structure is called *message*.
 Each message has a *name*.
 Together with the name of the *package* a message can be uniquely identified.
+A message has the URN: package/msg/name`.
 
 ### Services
 
 For request / reply style communication the two exchanged data structures are related.
 These pairs of data structures are called *services*.
-A service is identified by its *name* and the *package* it is in.
 Each service describes two messages, one for the request data structure, one for the reply data structure.
+Together with the name of the *package* a
 
 ### Actions
 
 For longer running request / reply style communication with feedback about the progress the exchanged data structures are related.
 These triplets of data structures are called *actions*.
-An action is identified by its *name* and the *package* it is in.
 Each action describes three messages, one for the goal data structure, one for the result data structure, and one for the feedback data structure.
 
+### Identifying data structures
+
+Every data structure can be uniquely referenced with a *uniform resource name* (URN) and a *uniform resource locator* (URL)
+as described by [IDL - Interface Identification](idl_interface_definition.html#interface-identification)
+
+#### Messages
+
+- URN: `<package_name>/msg/<name>`
+- URL: `<package_name>/msg/<name>`
+
+#### Services
+
+- URN: `<package_name>/srv/<name>`
+- URL: `<package_name>/srv/<name>`
+
+The underlying message definitions that make up a service are located in the same file (ie. have the same URL) and are in the `srv` namespace:
+
+- URN: `<package_name>/srv/<name>_Request`
+- URN: `<package_name>/srv/<name>_Response`
+
+#### Actions
+
+- URN: `<package_name>/action/<name>`
+- URL: `<package_name>/action/<name>`
+
+The underlying message definitions that make up an action are located in the same file (ie. have the same URL) and are in the `action` namespace:
+
+- URN: `<package_name>/action/<name>_Goal`
+- URN: `<package_name>/action/<name>_Result`
+- URN: `<package_name>/action/<name>_Feedback`
+
 ### Field types
 
 The type of a field can be either a primitive type or another data structure.