uri.proto

/*
 * 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: SOURCE
 * SPDX-FileCopyrightText: 2023 General Motors GTO LLC
 * SPDX-License-Identifier: Apache-2.0
 */
syntax = "proto3";

package uprotocol.v1;

option java_package = "org.eclipse.uprotocol.v1";
option java_outer_classname = "UUriProto";
option java_multiple_files = true;


// Data representation of uProtocol <b>URI</b>.
// This class will be used to represent the source and sink (destination) parts 
// of the Packet, for example in a CloudEvent Packet. <br>
// UUri is used as a method to uniquely identify devices, services, and resources
// on the  network.<br>
// Where software is deployed, what the service is called along with a version and
// the resources in the service. Defining a common URI for the system allows 
// applications and/or services to publish and discover each other.<br>
message UUri {
  // Authority of the URI (ex. device name, address, id), if not present, UUri is local
  UAuthority authority = 1;
  
  // Software Entity information (ex. name, version, id)
  UEntity entity = 2;
  
  // Service Resource information (methods, topics, etc..)
  UResource resource = 3;
}


// An Authority represents the deployment location of a specific Software Entity.
// Authority can be represented in either a name (i.e example.com), ip address (205.236.147.1)
// or an ID (i.e. VIN, SHA 128, or any other identifier that is less than 255 bytes.
// *NOTE:* When Authority is empty (neither name, ip, or id are set) the authority
// is local.
message UAuthority {
  optional string name = 1; // Domain & device name as a string
  oneof number {
    bytes ip = 2; 	// IPv4 or IPv6 Address in byte format
    bytes id = 3;		// Unique ID for the device, could be a VIN, SHA 128, or any other identifier
                    // *NOTE:* MAX length is 255 bytes
  }
}


// Data representation of an <b> Software Entity - uE</b><br>
// Software entities are distinguished by using a unique name and id 
// along with the specific version of the software.
// An Software Entity is a piece of software deployed somewhere on a uDevice.<br>
// The Software Entity is used in the source and sink parts of communicating software.<br>
// A uE that publishes events is a <b>Service</b> role.<br>
// A uE that consumes events is an <b>Application</b> role.
message UEntity {
  string name = 1;    // Name of the entity
  optional uint32 id = 2;      // The numeric ID for the uEntity assigned from the name/number registry
  optional uint32 version_major = 3; // optional major version of the uEntity
  optional uint32 version_minor = 4; // optional minor version of the uEntity
}


// A service API - defined in the {@link UEntity} - has Resources and Methods. 
// Both of these are represented by the UResource message.
// A uResource represents a resource from a Service such as "door" and an optional
// specific instance such as "front_left". In addition, it can optionally contain
// the name of the resource Message type, such as "Door". The Message type matches
// the protobuf service IDL that defines structured data types.
// An UResource is something that can be manipulated/controlled/exposed by a service.
// Resources are unique when prepended with UAuthority that represents the device and
// UEntity that represents the service. 
message UResource {
  string name = 1;      // Name of the resource
  optional string instance = 2;  // Instance of the resource
  optional string message = 3;   // Message type for the resource
  optional uint32 id = 4;        // Numerical representation of the UResource portion of the UUri
}


// Repeated list of URIs that can be used for batching APIs
message UUriBatch {
  repeated UUri uris = 1; // Repeated list of URIs
}