From 3943e9cf81f1fd5fb085e07f647185d027bfe73a Mon Sep 17 00:00:00 2001 From: Gareth Sylvester-Bradley <31761158+garethsb@users.noreply.github.com> Date: Mon, 17 May 2021 10:58:25 +0100 Subject: [PATCH 1/2] Use of URNs draft rewording --- docs/2.1. APIs - Common Keys.md | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/docs/2.1. APIs - Common Keys.md b/docs/2.1. APIs - Common Keys.md index 31573621..4c0f37cf 100644 --- a/docs/2.1. APIs - Common Keys.md +++ b/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 +``` +[.][/] +``` -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.` 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. +All subclassifications will share features with the concept identified by the associated base URN which will permit a common approach. -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`. +For example, the URN base `urn:x-nmos:transport:rtp` above has two subclassifications of `ucast` and `mcast`. -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.` 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. From 320c0d7bc9fccddacab93859608261a0df9f828d Mon Sep 17 00:00:00 2001 From: Peter Brightwell Date: Mon, 17 May 2021 12:07:07 +0100 Subject: [PATCH 2/2] Apply suggestions from code review --- docs/2.1. APIs - Common Keys.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/2.1. APIs - Common Keys.md b/docs/2.1. APIs - Common Keys.md index 4c0f37cf..46a694ec 100644 --- a/docs/2.1. APIs - Common Keys.md +++ b/docs/2.1. APIs - Common Keys.md @@ -95,9 +95,9 @@ where: - 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.` and SHOULD be handled as specified in [APIs](2.0.%20APIs.md). -All subclassifications will share features with the concept identified by the associated base URN which will permit a common approach. +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, the URN base `urn:x-nmos:transport:rtp` above has two subclassifications of `ucast` and `mcast`. +Further subclassifications might be defined for a URN base in the future. Versioned URNs will be used to indicate specification versions.