Merge pull request #166 from AMWA-TV/garethsb-patch-1

Use of URNs draft rewording

docs/2.1. APIs - Common Keys.md

@@ -83,22 +83,24 @@ See [Use of URNs](#use-of-urns) below for additional requirements regarding thei
 
 All Uniform Resource Names (URNs) specified within the scope of the NMOS specifications MUST use the namespace `urn:x-nmos:`. Manufacturers MAY use their own namespaces to indicate values of URN which are not currently defined within the NMOS namespace.
 
-Where a URN begins `urn:x-nmos:` it MUST use the following construction:
+NMOS specification URNs use the following construction:
 
-- The URN base is a sequence of one or more names delimited by `:` characters, including the namespace
-- The URN MAY include one or more 'subclassifications'
-- The URN MAY include a version number
+```
+<URN-base>[.<subclassification>][/<version>]
+```
 
-Subclassifications are defined as the portion of the URN which follows the first occurrence of a `.`, but prior to any `/` character. By convention, URNs which begin `urn:x-nmos:` will never include a further `:` after the first occurrence of a `.`.
+where:
 
-For example, the URN base `urn:x-nmos:transport:rtp` above has two subclassifications of `ucast` and `mcast`.
+- the URN base is a sequence of one or more names delimited by `:` characters, beginning with the namespace `urn:x-nmos:`.
+- the optional subclassification is the portion of the URN which follows the first occurrence of a `.` prior to any `/` character. By convention, URNs which begin `urn:x-nmos:` will never include a further `:` after the first occurrence of a `.`.
+- the optional version is the portion of the URN which follows the first occurrence of a `/`, up to and including the remainder of the URN. By convention, URNs which begin `urn:x-nmos:` will format the version as `v<MAJOR>.<MINOR>` and SHOULD be handled as specified in [APIs](2.0.%20APIs.md).
 
-API clients interpreting URNs MUST correctly recognise any as-yet undefined subclassifications as being associated with the URN base which appears prior to the first `.` character.
+A subclassification is more constrained than its URN base.  For example, the URN base `urn:x-nmos:transport:rtp` above has two subclassifications of `ucast` and `mcast`.
 
-For example, if filtering by the format `urn:x-nmos:format:video`, the filter includes any as-yet undefined subclassifications such as `urn:x-nmos:format:video.raw`.
+Further subclassifications might be defined for a URN base in the future.
 
-Versions are defined as the portion of the URN which follows the first occurrence of a `/`, up to and including the remainder of the URN. Any `.` characters after this point indicate a version delimiter. By convention, URNs which begin `urn:x-nmos:` will format the version as `v<MAJOR>.<MINOR>` and SHOULD be handled as specified in [APIs](2.0.%20APIs.md).
+Versioned URNs will be used to indicate specification versions.
 
 For example, the URN `urn:x-nmos:control:sr-ctrl/v1.0` can be separated into a base `urn:x-nmos:control:sr-ctrl` and version `v1.0`.
 
-Query API clients MUST be tolerant to URNs which have not yet been defined, but which might be added in later API versions.
+API clients MUST be tolerant to URNs which have not yet been defined, but which might be added in later API versions.