Documentation - request for definition of Terms

[gunnarx]

On the previous meeting I was requested to start on a draft of terms definitions, to find consensus around the most key concepts of the VSC language. First proposal below.

[gunnarx]

• Service
  • (General) A service is a software functionality or set of functionalities that can be activated by a client. A key characteristic of a service in support of SOA is that it has low coupling to other services and strives to provide a useful function also if used independently from other services.
  • (VSC) A VSC Service contains one or more 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.
  • A Service name is not in itself a Namespace, but its contents must be defined within at least one Namespace. The Namespace in question 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 mentioned within this file*.
  • A file can contain a maximum of one Service.

> (To be further determined - how complete is our include/reference concept?)

• Namespace
  • A namespace is a way to separate definitions in named groups.
  • Namespaces are used to ensure that local names will not clash with identically named items in other namespace.
  • Namespaces usually 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 generally assumes that items within different (non-parent) namespaces are isolated from each other unless otherwise specified, and that common hierarchy rules apply (i.e. everything within a child namespace can see and reach items in any of its parent namespaces without a specific required statement of reference or inclusion).
• Interface
  • (General)
    • very broad term...
  • (VSC)
  • A VSC Interface is primarily defined by a collection of Methods.
  • An Interface name is not itself a Namespace but must be defined within a Namespace.
  • 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.
  • The VSC interface definition language strives to usable in all areas of a computing system. The VSC Interface object is therefore a pure software function focused definition, which does not define details around communication hardware, target language, communication protocols etc. Such information is added through supplementary information later.
• Method
  • A method is a function with a (mandatory) name, and a set of input parameters, output parameters, and error conditions, all of which are optional and may be empty/undefined.
  • Like most other objects, a Method is always defined in the context of a Namespace, but this is most often implicitly determined because the Method is defined within the context of an Interface/Service
• Error
  • 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 - this translation is target language/environment specific.
    • It may be added as return/output parameters in one programming language and translated to Exception-handling in another. Communication protocols may implement their own error-condition channels and approaches.

[slawr]

A good start. Reading..

A key characteristic of a service in support of SOA

I think you should at least spell out SOA in the first use.

all Interfaces that make up a service must be mentioned within this file*

There seems to be no corresponding reference. Is it supposed to be referring to the sentence prefixed with '>' a couple of paras down?

[erikbosch]

Better to put it in a *.md file in a PR to simplify review? Good start - I think it would be good to add at least placeholders for Events and Properties, to clarify difference between Methods/Events/Properties.

[erikbosch]

Concerning streaming replies we had some discussion on slack in April 4th-5th in rpc channel. There I created a proposal:

• Atomic VSC calls are methods specifying "out" parameters.
• Stream VSC calls are methods specifying "event(s)" instead of "out"
• A VSC method cannot specify both "out" and "event"

With this definition a "typical" VSS read or write would be an atomic call, while a "typical" VSS subscribe would be a stream call. Magnus included some examples in Slack. This way we can already in VSC express that e.g. MoveWindow is a stream call where you can get zero or more events showing current position of window and status of the request

With the definition above we can define "event" as something that is either broadcasted by the server, or received triggered by a method.

For property we could possibly describe it as a shortcut for get/set-methods, e.g. if you specify property X, that gets the same results as specifying the two methods getX and setX.

[slawr]

With the definition above we can define "event" as something that is either broadcasted by the server, or received triggered by a method.

For property we could possibly describe it as a shortcut for get/set-methods, e.g. if you specify property X, that gets the same results as specifying the two methods getX and setX.

Easier for me to say at the high level, than it be proven in the details but wouldn't there be value in staying as close as possible and ideally logically equivalent, to the approach in OpenAPI and AsyncAPI? Although possibly not in definition format if that is hard to cherry pick or that does not make sense for other reasons. Equivalence or a sub-set of it supports smoother integration. Particularly for those coming from those worlds.

[gunnarx]

Atomic VSC calls are methods specifying "out" parameters.
Stream VSC calls are methods specifying "event(s)" instead of "out"
A VSC method cannot specify both "out" and "event"

I am making a different proposal that could be summarized as:

1. Return Value is a unique thing (it could be done with "out" parameter, but I think we should have a special status for it. Having a return value is common behavior for most programming environments. And if some environment does not support it, it can be converted to an out parameter in the code generation of course.)

2. Return values can be sent at the end of the method, or continuously. One concept works for both, and I think it makes sense because it serves the same purpose (communicate if execution has completed and/or if successful).

The core reason for this this is that the Methods should be defined the same way whether they are later executed as blocking or non-blocking, instead of making this choice already when the method is defined. In other words, we can delay the decision of whether a method is of the blocking or non-blocking type. In some cases this is also limited by the target environment, so if you avoid making this choice immediately then the API is more reusable in many contexts.

The full text proposal is coming, so I propose to give feedback there.

EDIT: I think the above is the simplest way (explicitly name the Datatype of the return value), but something that could be considered is if a return value could be equal to an already defined Event. Let's see after we have agreed on the description of Event.

[gunnarx]

See COVESA/vehicle_service_catalog#41 for a PR where you can comment if you prefer it

[gunnarx]

Since this is a question for the definition of the language/interface-model that is now IFEX project, the issue will be transferred from Vehicle Service Catalog project to IFEX project.