-
Notifications
You must be signed in to change notification settings - Fork 12
Home
The purpose of this document is first to provoke discussion and eventual rough consensus around the meaning of terms used to describe VSC and its technologies.
Many of these are general Computer Science terms that have been defined in different ways in different places. Therefore, these definitions will not match every system or personal opinion out there, but it is important to find as much consensus as possible, to align with other similar systems, and in the end to clearly define what things mean in VSC terms.
Please provide feedback, in order to align these terms as closely as possible to common understanding. When arguing for a different meaning, try to provide references to the documented meaning in other related systems.
The document also states a few of quite specific behaviors that go a little bit beyond pure definition of terms. The purpose is strive towards a strict and clear understanding of the behavior/semantics of the VSC language and associated tools. An example of such a statement would be "There can be only one service per file". Once again, the purpose is first to provoke discussion, and get feedback on the consequences.
This means all content that is described using only the Interface Description Language, not supplementary files or layers. A VSC Interface Description is designed to be as independent of the target technology as possible, and as reusable as posible. VSC as a project, technology, and concept encompasses a whole lot more, but the VSC-IDL (the Interface Description) shall not include any information that is target-dependent or unique for a particular environment.
For each type of output result from a generator or conversion tool, there will be environment-specific details to consider, and in this proposed terminology we refer to all of those as simply the "Target Environment". Target Environment is a catch-all term to indicate the context and environment of artifacts that are generated from IDL, plus additional supplementary information. The term means any and all things that are unique about that environment, or looking at it another way - any and all details that cannot universally be determined by reading only the Interface Description. The target environment details will be involved in a particular interpretation of the generic Interface Description.
Examples:
The chosen programming language in the case of code-generation tools is part of target environment. Also any details relating to specific software technologies that are being targeted. For example if HTTP is an applicable protocol to use, then the choice of this protocol is part of target environment. Furthermore, details of transport layer security (TLS) would apply if HTTP is used, whereas for other protocols it might not. Anything related to TLS is thus part of the HTTP focused target environment - it is not part of the Interface Description.
N.B. In some of these texts, "target-environment dependent", may sometimes be shortened to simply target-dependent or something similar.
A Namespace is a way to collect entities into named groups. Namespaces are used to ensure that local names will not clash with identically named items in other namespace. To achieve this, Namespaces also separate what objects can be seen or reached from within a part of a program. Namespaces can contain other Namespaces, creating a hierarchy. How visibility/reachability is handled might be specific to the target language or environment, but VSC expects the following behavior to be the normal one unless there are very good reasons for exceptions: Items within different (non-parent) namespaces are logically isolated from each other unless otherwise specified, and these common hierarchy rules apply: Everything within a child namespace can see and reach items in any of its parent namespaces. For a non-parent relationship, it is required to either specify an item using a fully-qualified "path" through the namespace hierarchy, or to make a statement of reference or inclusion of another namespace into the current namespace.
Generally, Interface is a broad term. VSC is concerned with functional software interfaces.
The VSC interface definition language strives to usable in all areas of a computing system. The VSC Interface definition does not define details around communication hardware, implementation language, data-communication protocols, bit-encoding and in-memory layouts etc. Such information is however added through supplementary information in the mappings and tools that consume the interface description. In this environment the content of an Interface are things like methods, data item definitions (Properties), Events, and supplementary definitions needed to make use of them, such as type definitions, constants, etc.
A VSC Interface is primarily defined by a collection of Methods, but may also expose functionality through events and data properties/attributes. The interface may also include variables, constants, data types, observable data-items and events, but some of them may also be defined within the same namespace the interface belongs to, (or elsewhere if referenced correctly). As long as they are visible from the interface, they can be referenced in the interface.
The VSC definition of an Interface name does not itself introduce a Namespace level, but the Interface content will always be defined within some Namespace. (*N.B. In certain target environments however, the translation of Interface into its target representation (e.g. abstract Class) might still function as a namespace in that programming environment. The translation will take care of what is required to make the translation accurate).
All Methods defined or referred to by an Interface are required to be within the same Namespace, i.e. it is not possible to build an Interface by referring to Methods that have been defined in different Namespaces.
(General) A service is a software functionality or set of functionalities that can be activated by another user, system or system component (generally referred to as a client). An important characteristic of a service in support of SOA is that it fulfills a fairly specific and limited purpose, as long as it also has low coupling to other services and strives to provide a useful function also if used independently from other services.
A VSC Service contains one or several Interfaces, which are defined or referenced within the service definition. The service definition may within its namespace also define Types, constants and other definitions required to make use of the service.
Defining a Service does not itself introduce a Namespace level, but the its content will always be defined within some Namespace. The used Namespace is referenced or defined from within the Service definition.
A Service must have its fundamental definition in one single .yaml formatted file, although this file might use references to other parts. In other words, all Interfaces that make up a service must be defined, or "included" from within this file.
In the standard VSC tooling, a single file contains a maximum of one Service, so the file can be used as a method of differentiating services. NOTE: In certain tool environments, it is of course possible to combine several files into one file before processing the input, but that would be a tool-specific handling.
A method is a single software operation (a.k.a. function) with a (mandatory) name, plus a set of (optional) input parameters, output parameters, and error conditions.
Like most other objects, a Method is always defined in the context of a Namespace, but this is often implicitly determined when the Method is defined within the context of an Interface/Service.
A VSC Error definition is an error condition that can appear while attempting to execute a given Method. An error is defined by referencing one or more Types that define the data that shall be communicated when an error occurs. Enumeration types are common, but it could be any defined type. There can be more than one error type defined for a method.
It is not specified by VSC how errors are propagated to the caller of a function - that translation is target environment specific. In other words it might be a return or output parameter in one programming language but using Exception-handling in another. Communication protocols might embed errors in a response message, or implement some other side-channel for error propagation, or other methods.
TBD: Should error also be defined by its name (unique, at least within the namespace), or is it enough to reference its type. Is this error name reusable across methods, or is it enough that the datatype(s) are reused by methods?
A Property is an observable data item. It belongs in a Namespace, has a canonical name in addition to possible aliases (i.e. alternative names), and a data type. A Property is defined as a single item but the data type could be an arbitrary data type, including composite data types.
The singular nature of a property suggests that it is generally expected behavior that its value shall updated and communicated as an atomic operation, i.e. it is either fully updated or not at all.
The available features for update and communication are target-environment specific, but the most common expectation is that a Property can be updated and observed, meaning that a client can call a method to get or set the current value of the property (with appropriate access control rules) and often also subscribe to be notified of when the value of a property was changed for any reason.
In some other language definitions this type of item is called an Attribute or Field. A property can also be seen as analogous (and bi-directionally translatable, if datatypes allow it) to a sensor Signal in the Vehicle Signal Specification (VSS).
Side proposal: Consider renaming Property to Attribute to match Franca IDL, and because properties have another use in OpenAPI and AsyncAPI, and it seems other HTTP-related communication as well.
A Return Value specifies what is returned from a Method execution. Although "out parameters" could serve a similar purpose, the Return Value has been given special status.
Only one return value type is defined per method.
NOTE: Please be aware that while return-value is often traditionally used for indicating success/error, the generalized Errors concept is more powerful and should often be preferred.
There is only a single return value type, but it can use any data type, including composite types. The term Status may be used in other technologies and the meaning of return value shall be seen as equivalent of status.
In computing systems there are two main paradigms regarding invocation of a procedure/function: Blocking/synchronous vs. Non-blocking/asynchronous.
In a blocking/synchronous environment, the client that invokes an operation (i.e. calls a function) will halt until the operation is completed and "returns". Upon return, a return-value (result) may be communicated back to the client, and it then continues its normal execution flow.
In an asynchronous setup, a client can trigger the start of an operation and then continue doing other work while the method executes in parallel. In this case, the executing function will report back when the operation is finished, but it could also give continuous reports as to the progress of the function ("streaming updates").
In the VSC-language, methods can be defined without defining their invocation strategy (synchronous/asynchronous). It is more flexible to define this separately in a deployment-model/target-mapping because it leads to interface descriptions that can be reused in a wider set of circumstances. The desire for sync vs. async may change in different circumstances, and the availability of sync/async might be constrained by the target environment capability.
In all cases, a Method in VSC-IDL-language (optionally) defines a Return Value type. VSC-IDL-language has the unique feature of using the Return Value type to serve different purposes in sync vs async situations:
In this manner, the same concept (return value) can be defined for the interface, without knowing the manner that the function will be invoked (e.g. the chosen communication protocol)
Although some details are often target-dependent, the following defines the expected behavior of the return typein a system built from a VSC interface:
- In the case of a blocking/synchronous call, the Return Value type is the value communicated once after the operation completes.
- In the case of a non-blocking/asynchronous call, the same defined Return Value type is also used with the difference that it may be returned multiple times. Using this behavior is optional and target-dependent, but if it is used then a target environment may choose to provide a regular stream of status updates while the method executes. In each such update, a value is transferred that matches the defined Return Value type**.
It follows that only valid values of the Return Value type shall be returned.
** Design note: This is already in itself a very powerful mechanism and should suffice in a majority of cases, but if any additional status/streaming-data functionality is required, that may of course be done by defining a data Property in the interface, whose value is some kind of status update for the executing method. There is no formal way to describe the relationship between Property and Method in this secondary approach - it would rely on documenting the relationship.
***Design note 2: While the interface can now be defined without deciding up front about synchronous/asynchronous operation, if an async operation may be expected it is still a good idea to design the return value for this. It would probably include something to indicate that processing is under way. For example the streaming returns during an operation might be: Started, Processing..., Processing..., Processing..., Done!"` (Note that adding/changing return value can, like most features, be extended by overlays.)
After an operation has been completed and its equivalent of "DONE" has been communicated, the function is expected to seize any further communication of the return/status type.
A return value can naturally indicate that the operation did NOT complete successfully, but the more capable Errors concept should not be overlooked.
An Event is a time-sensitive communication with fire-and-forget behavior, sent between parts in the distributed system.
A VSC Event can carry multiple pieces of data with it, each of which can use an arbitrary data type.
A VSC Event definition actually looks similar to a Method but with some differences in definition and behavior: An Event has a name, and optionally a set of parameters that are distributed with the event, each having a name and a datatype. This is something that mimics a Method signature. An Event can however not have a Return type, nor any out-parameters.
Fire-and-forget expected behavior means that on the VSC semantics level it is not expected to be a guaranteed delivery. It is decided by the target environment mapping whether an Event can be guaranteed to be received or if it is non-reliable. In either case, there is no reply defined for an Event. A Method call shall be used where reliability is required, in which case a return value would indicate that the request was received and completed.
A VSC Event is a separate and expressly defined object in the interface description. It is therefore not (in our particular definition) to be mixed up with any other "happenings" in a system that are not defined inside a VSC/interface definition. It shall not be confused with happenings/messages that are automatically sent by some target environment because of the defined behavior of its objects. For example, in some systems, subscribing to changes of an observable data Property, may trigger something that some might call "update events", but that is a consequence of the behavior of the observable Property, and is not to be confused by expressly defined Event objects. It is simply not needed to define any VSC Events for such messages that are created automatically by the particular data protocol or target environment mapping.
A VSC Event is also not a persistent data item, and thus has no concept of active-low, edge-trigger, rising/falling edge, etc. (other than what its name and documentation indicates**). The Event is simply transferred by the sender when the sender thinks it is appropriate, and the documentation would explain what the meaning is of this particular event.
** Design tip: If there is a desire to model On/Off events, and avoid the verbosity of duplicating everything into two different Event objects -> simply give the event a single name and transfer a boolean as argument: FooState(bool) where true/false indicates the on/off state. Another option, as always, is to define an observable data Property and use the target environment's Pub/Sub capability to get updates. (Depending on the guarantees given by the target environment, the latter might give reliability guarantees that Events do not have).
An Event can be sent from client to server or from server to client(). () TODO: Shall the direction of an event be defined somehow?
** If an event is to be transferred as a "broadcast" in a particular environment whereas other Events would be addressed uniquely to a particular client, then define this difference as extra information in a deployment model / target mapping. It is not specified in the interface description.