The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in IETF BCP14 (RFC2119 & RFC8174)
Copyright (c) 2023 General Motors GTO LLC Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. SPDX-FileType: DOCUMENTATION SPDX-FileCopyrightText: 2023 General Motors GTO LLC SPDX-License-Identifier: Apache-2.0
URIs are used to uniquely identify (or address) stuff such as devices, software entities, topics, methods, etc…). A common URI definition allows stuff to be addressable anywhere on any heterogeneous system.
The standard URI format is defined in RFC3986 and illustrated in the figure below.
URI specifications are covered at length in RFC3986 and will not be covered in this document, we will focus on the additions to RFC3986 that are specific to the uProtocol.
The following is taken from RFC3986 Appendix-A and shall be used as reference in this specification:
gen-delims = ":" / "/" / "?" / "#" / "\[" / "\]" / "@"
sub-delims = "!" / "$" / "&" / "'" / "(" / ")"
/ "*" / "+" / "," / ";" / "="
pchar = unreserved / pct-encoded / sub-delims / ":" / "@"
unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~"
reserved = gen-delims / sub-delimsURI Specification diagram below provides an overview of the specifications that we will elaborate in this document.
A uProtocol URI can be represented in the following formats:
-
UUri Data Model: Object format (declared in protobuf)
-
Long URIs: UUri object serialized to a string containing names (i.e. human readable)
-
Short URIs: UUri object serialized to a string containing numeric ids
-
Micro URIs: UUri serialized to a byte array (i.e. machine readable).
This section shall explain the requirements for each SDK to implement such that the mental model is the same across all programming languages. Data Model diagram below illustrates the UUri data model as well as includes the requirements for the naming convention for the various APIs.
|
Note
|
Resolved UUri refers to a UUri that contains both names and numbers (ids) meaning the UUri could be serialized to any of the given formats defined in Serializers below. |
-
MUST be declared in protobuf such that the definitions can be shared across all programming languages
-
MUST Follow the type names, member variables, and method names as defined in the diagram above
|
Note
|
please refer to link:../../up-core-api/uprotocol/uri.proto for the data model definitions |
In the next section we shall define the per-language requirements for the UUri data model. These classes are meant to facilitate the use of the UUri data model in the respective language (i.e. serialize, validate, etc…).
UriValidator is an interface with static methods to validate the UUri Data Model and check properties of the UUri such as if it contains the information to serialize to Long form or micro form, etc…
| API | Description |
|---|---|
|
Validates the UUri object and return
|
|
Validate that the
|
|
Validate that the
|
|
Return true if: |
|
Returns true if the Uri part contains names so that it can be serialized to Long URIs. |
|
Returns true if the object contains no information |
|
Returns true if the object contains both names and numbers (ids) such that it can be serialize to both Long URIs and Micro URIs |
|
Returns true if the Uri part contains the required ids to serialized to Micro format and the fields of the Uri can fit within the specified number of bits and bytes. Both sets of details can be obtained under Micro URIs |
|
Returns true if the Uri contains the required ids to be serialized to Short URIs. |
|
Returns true if: |
|
Returns true if: |
UriSerializer is the interface that defines the serialize and deserialize methods for the different types of serializers. We will explain each serialization format in this section.
Long URIs are UUri objects that have been serialized to a string containing human readable name of the UUri.
| Item | Value | Description |
|---|---|---|
|
|
Scheme (protocol name) |
|
unreserved |
Canonical hostname of the device following RFC1035 requirements. |
|
pchar |
The uEntity name |
|
pchar |
uEntity major version number only. |
|
pchar |
The name of the resource. For methods, this is fixed to |
|
*( pchar / "/" / "?" ) |
Protobuf message name as defined in https://developers.google.com/protocol-buffers/docs/overview. |
Additional URI Protocol Rules:
-
MAY contain scheme
-
A segment in the path (UE_NAME, UE_VER_MAJOR, URESOURCE_NAME) MAY be empty, resulting in two consecutive slashes (//) in the path component, this is equivalent to a wildcard
-
Schema and authority MUST be case-insensitive per RFC3986
-
Path, query, and message MUST be case-sensitive
If a segment in the path is empty:
-
The path MUST NOT start with "//"
-
Path MUST be path-abempty (i.e. its value can be either an absolute path or empty)
|
Note
|
Local URIs do not contain the authority and begin with / (forward slash)
|
Short URIs are UUri objects that have been serialized to a string containing only numeric values of a UUri.
| Item | Value | Description |
|---|---|---|
|
|
Scheme (protocol name) |
|
unreserved |
IPv4 address per RFC791. |
|
unreserved |
IPv6 address per RFC4291. |
|
unreserved |
Identifier *MAY* be a valid vehicle VIN (17 MSB) *MUST* fit within 255 bytes (when used for micro form) |
|
pchar |
The UEntity identifier |
|
pchar |
uEntity major version number only. |
|
pchar |
The unique identifier for the resource. |
Additional URI Protocol Rules:
-
MAY contain scheme
-
A segment in the path (UE_ID, UE_VER_MAJOR, URESOURCE_ID) MAY be empty, resulting in two consecutive slashes (//) in the path component, this is equivalent to a wildcard
-
Schema and authority MUST be case-insensitive per RFC3986
-
Path, query, and message MUST be case-sensitive
If a segment in the path is empty:
-
The path MUST NOT start with "//"
-
Path MUST be path-abempty (i.e. its value can be either an absolute path or empty)
|
Note
|
Local URIs do not contain the authority and begin with / (forward slash)
|
Micro URIs are used to represent various portions of the URI in byte array format using only the IDs for various portions of UAuthority, UEntity, and UResource. Micro URIs may be used in the uProtocol transport layer (uP-L1) to reduce the size of the URI and improve performance. There are two types of Micro URIs, they are local and remote where remote contains an address (IP or ID) and local is without an address (refer to some uThing that is local to the device).
-
All fields of micro UUri MUST be populated
-
Fields are Big-Endian unless otherwise specified
| Field | Size(Bits) | Description | Requirements | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
8 |
Current version of this specification |
MUST be 0x01 |
||||||||||
|
8 |
Type of Micro Uri |
MUST be one of the following values:
|
||||||||||
|
16 |
The ID assigned to the topic in the proto (unique per uE) |
|||||||||||
|
32 or 128 |
UAuthority IP Address |
MUST be a valid IPv4 or IPv6 address |
||||||||||
|
8-2040 |
UAuthority ID |
MAY be a valid vehicle VIN (17 MSB) |
||||||||||
|
8 |
Length of bytes for the UAuthority ID |
MUST be greater than 0 |
||||||||||
|
16 |
UE Identifiers |
|||||||||||
|
8 |
UEntity MAJOR version |
MUST be a valid MAJOR version |
||||||||||
|
8 |
Unused bits |
MUST be 0x00 |
Local UUris do not contain authority and SHOULD be used at all times when addressing uThings within the same uDevice.
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| UP_VERSION | TYPE | URESOURCE_ID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| UENTITY_ID | UE_VERSION | UNUSED |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Remote UUris mean that the uThing is running on a different device and we need to address the uThing using the device name, IP address, or an arbitrary length id (1-255 bytes).
-
Remote UUris MUST contain the UAuthority address (IP or ID) and MAY contain the UAuthority name.
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| UP_VERSION | TYPE | URESOURCE_ID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| UENTITY_ID | UE_VERSION | UNUSED |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| UAUTHORITY_ADDRESS (IPv4 32bits) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| UP_VERSION | TYPE | URESOURCE_ID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| UENTITY_ID | UE_VERSION | UNUSED |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
| UAUTHORITY_ADDRESS (IPv6 128bits) |
| |
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| UP_VERSION | TYPE | URESOURCE_ID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| UENTITY_ID | UE_VERSION | UNUSED |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| ID_LEN | UAUTHORITY_ID (1=256 bytes) ... |
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+The following examples are based off the USubscription notification topic (see usubscription.proto).
| Format | Value |
|---|---|
Long |
|
Short |
|
Micro |
|
| Format | Value |
|---|---|
Long |
|
Short |
|
Micro |
|
| Format | Value |
|---|---|
Long |
|
Short |
|
Micro |
|
| Format | Value |
|---|---|
Long |
|
Short |
|
Micro |
|
Wildcard are used to replace portions of the URI to perform pattern matching (i.e. subscribing to multiple topics, searching for services, etc…). Wildcard are represented in a long or short URI only when the segment is blank.
|
Note
|
Not all implementations and uEs support wildcards, please refer to the implementation and uE documentation for more information. |
When a UUri is not resolved (only contain either names or ids), the only way to resolve the UUri is to lookup in uDiscovery the missing information. UEntity name and numbers are declared in the uService’s protos by adding the service metadata attributes using Protobuf Options. This information for the uE is then exposed through the uService generated stubs.
UResource portion of the UUri is also encoded in the uService protos and can be fetched by application developers using MessageDescriptors. Application developers are then able to easily construct resolved UUris using the above mentioned generated code. Dispatchers however do not have the name-to-number mapping metadata as they are only provided either serialized Long or Micro Uris so if they have to send a Uri in a different format, they have no choice but to dynamically lookup (resolve) the Uri.
|
Important
|
If a uE has a specific Uri format requirements (Long vs Micro), they MUST document them in their respective APIs specifications. Please see Core uProtocol uEs for more specific requirements for uProtocol core services. |