covesa / vehicle_service_catalog Goto Github PK

In the license file in the repo we state MPL 2.0:

https://github.com/COVESA/vehicle_service_catalog/blob/master/LICENSE

But in the README we state:

This document is licensed under Attribution 4.0 International License described here

I believe this is at least confusing, as the license statement in the README might be interpreted as concerning the whole repo. I do not know if there are any legal problems stating different licenses in different places. I do not know if we can/want/must keep different licenses for the repo and the README. If we want to keep the syntax definition with a different license we shall maybe move it to a separate file, so we in the README can mention the general license for the repo (MPL, similar to how is used in VSS).

FYI: @magnusfeuer - as you are the author I think your view is important.

The current "Property" concept in the IDL describes an individual, named, and observable data item. Once translated to some executable envirionment it can be accessed through some operations that provides get, set and/or subscribe-to-changes capabilities.

I am in the process of comparing related IDL projects and their terminology to have alignment where possible.

Looking at a typical OpenAPI (formerly Swagger) definition, it seems to me that the word properties is used to indicate a list of variables/parameters that are defined for a particular path (URL). It is either directly, or by reference to a JSON-schema, indicating the format of the JSON document that is to be exchanged on that particular path/URL (i.e. what is being returned from the server by a GET operation, or provided by the client as part of a POST op.). The word properties defines the data items that are to be defined in the JSON document.

SIDEBAR: The word properties also seem to be used a bit more generally (unless I am missing the semantic equivalence) in other parts of the specification, when talking about various things that can be configured (i.e. things that have a name, and can be assigned a value), but this is related to meta-information or modifying generic behavior. We are not then talking about data that is part the application API (because that is what specified uniquely for a particular application itself and so by definition could never be written in a specification of the OpenAPI definition language itself).

In a REST interface, the path/URL represents a particular part of the system to be accessed, or if it's a complex API, its hierarchical 'namespace' path and ultimately the name of the particular operation. (the 'operation', with the understanding that the HTTP operations GET/POST/PUT can then be overlaid on that same path, to vary the behavior). Even with this overlay capability, the path/URL seems to (often) represent a kind of operation that can be achieved through the web API***

In any case, studying today's "Web APIs" these properties that make up JSON document, are either the "input" information in a POST operation or the "return value" of a GET operation, and therefore seem akin to the provided parameter/argument -list of a method call, or the return value from a method call. (We disregard for the moment that you can also encode data in the query-string of the URL itself, e.g. arg1/arg2 in this example: https://server/application/group/do_this?arg1=foo&arg2=bar because it does not really change the outcome of this discussion).

Therefore, Properties in web interfaces (let's assume OpenAPI as setting the direction for terminology in that domain) seem to me most often similar to the parameters of a RPC method call.

Counterpoint: It is tricky because if you consider the URL to be pointing to a data object (a document in the original HTTP meaning, the web being designed firstly to exchange web pages that are documents rather than performing operations on an "API"), then performing GET/POST operations on that item would be similar to interacting with a "named, observable data item". To be clear, I am here proposing that the path/url is sometimes our "Property", but the properties of the JSON document might in this case overlap in the sense that the JSON is providing values for the Property at that path/URL. But this is a fairly special case and in that case we can just be happy that things match. It still won't help other mismatching cases.

So if on the other hand, the JSON document is considered to carry one-or-several "property values" (consistent with the terminology of OpenAPI and JSON-schema) then our definition of Property might be considered to match roughly, but this is only one case and guaranteed for many web-style interfaces.

This is the first example from the original swagger web site. The path '/users' is essentially a path that, once you overlay the GET and POST HTTP operations, provides a "setUser_s_" and "getUser_s_" style of API. Look at how the properties are id and name. These properties are the ones allowed by the definition to be in the exchanged JSON, and they are used in OpenAPI to indicate a group of parameters that are specific to this URL and therefore more resembling parameters/arguments for the operation/method. If we were to translate this to the concept we are here discussing then "users" would be the Property/Attribute, since that is the observable data item but the id and name are not of themselves a "named, observable data items", they are values assigned to the data item, and the operation is in fact designed to add a single user, not to overwrite the entire "users" object.

These comparisons are not always obvious because we are looking at different programming paradigms when comparing REST/HTTP to RPC type interfaces, and also because any mechanism provided by a programming environment can and will be used/misused in different ways. In other words, counter-examples are likely to exist and there is more than one way of doing it, but we should consider the consequences of each case, perhaps with emphasis on what is the most common.

In conclusion, what I'm trying to propose, is that for Web APIs, the word properties, in most cases acts as method-parameters/arguments/return-value instead of meaning an individual observable data item. Our "named, observable data items" live as a siblings to the methods, not something that belongs to a specific method. They are part of an Interface, not part of a particular method.

In the few cases where the definitions might overlap today, this is still not a problem if we rename it. We can still agree that for those particular cases, the concept of the observable data item (under a new name) would be translated to a property also in the OpenAPI world. But it would be bad to have overlapping terminology, if for a majority of cases it means something quite different.

At this point I am raising this question to rename the current Property to Attribute and to ask for any other proposals.

By the way, the word Attribute is already what is used in in Franca IDL for the concept we are discussing.

A counterpoint might be that attribute is (I believe) is used in some systems to indicate something more similar to a constant value. (Further investigation could solidify our basis for decision). In particular, VSS uses attribute in this manner.

There are some ideas on importing/integrating VSS into VSC. Then comes the question up on how to name services/namespaces. If we take our current service as example:

https://github.com/GENIVI/vehicle_service_catalog/blob/master/comfort-service.yml

• The service is called "comfort"
• The namespace is called "seats"

But in VSS we have today for seat-related signals paths like Vehicle.Cabin.Seat.Row1.Pos1. If we would like to integrate/import VSS into VSC we have two options:

• Make sure that services and signals referring to the same feature (e.g. a seat) exist in the same logical location. I.e. the method current_position shall exist in the same service/namespace as the VSS signal lumbar
• Logical separation, e.g. by retaining existing VSS-paths in a separate VSC service.

I could see a value if we could have a representation where logically related services and signals when imported to VSC reside in the same service or at least in the same namespace. So that if you in the future a generated API/SDK easily could find all signals and methods available for your seat.

Have there been any thoughts on how to best structure services and namespaces in VSC? Naming conventions and similar?

• name: position_t
  type: struct
  description: |
  The position of the entire seat
  members:
  - name: base
  type: movement.movement_t
  description: |
  The position of the base 0 front, 1000 back
  - name: cushion
  type: movement.movement_t
  description: |
  The position of the cushion 0 short, 1000 long
  - name: lumbar
  type: movement.movement_t
  description: |
  The position of the lumbar support
  - name: side_bolster
  type: movement.movement_t
  description: |
  The position of the side bolster
  - name: head_restraint
  type: movement.movement_t
  description: |
  The position of the head restraint 0 down, 1000 up

@gunnarx, @magnusfeuer I'm really concerned about yet another definition of vehicle concepts in the interface description throughout the seat example. Why aren't you using VSS, where possible?

As mentioned in #42, and the link provided there shows that COVESA has formalized requirements to prefer DCO/sign-off procedure to be used for all contributions (unless the contributions are provided under a CLA which may have other requirements).

Shall we specify contribution guidelines and shall we start requiring DCO/signoff more rigorously in this project and in vsc-tools?

The datatypes described in the current documentation are copied from VSS.
VSS later removed byteBuffer type. It is assumed that an array of uint8 will serve the same purpose.

We have a few service examples in https://github.com/GENIVI/vehicle_service_catalog/blob/master/comfort-service.yml but they do not involve any type of error handling. A lot of errors can of course happen when someone call a service, like:

1. • Server/Receiver is not reachable
2. • Caller is not to authorized to perform the operation
3. • Argument given is out of range (e.g. requesting 2000 as movement_t)
4. • The particular vehicle does not support parts of the service, e.g. does not have a moveable lumbar.
5. • Movement is mechanically blocked
6. • Technical error, e.g. seat engine broken

I am aware of that the current example is just an example, but what type of errors do we want to be part of actual method definitions, and what should be part of the actual implementation/realization.

Shall it possibly be so that errors that typically happen "inside the vehicle" (error 4-6 above) shall be covered in VSC method, but others related to e.g. authentication/authorization shall be handled by the implementation, i.e. not visible in VSC definition of the method?

We discussed complementing the technical work on the IDL with focusing on describing more examples of standard services.
... the purpose being to show the value of this work through showing the end result of common service/API descriptions.

• HVAC
• Seats
• Tuner AM/FM
• SOTA
• Remote door unlock
• Vehicle tracking

Some of these may be good examples to exemplify how service descriptions may interoperate with VSS signals (including actuators that are expected to be "target value" when written).

We currently have a seat comfort example service. As of today the semantics is not really aligned with VSS. As an example, in the VSC example we seem to use relative values to describe position (from 0 to 1000). In VSS we use absolute numbers. We should preferably in the future use the same semantics for both, i.e. either absolute in both or relative in both.

Cushion use in VSC relative value:

https://github.com/COVESA/vehicle_service_catalog/blob/master/comfort-service.yml#L65

- name: cushion
            datatype: movement_t
            description: |
              The position of the cushion 0 short, 1000 long

https://github.com/COVESA/vehicle_signal_specification/blob/05a678095d497d32e6053f444bbaca1ac8bea032/spec/Cabin/SingleSeat.vspec#L81

Cushion.Height:
  datatype: uint16
  type: actuator
  min: 0
  unit: mm
  description: Height of the seat cushion (leg support), relative to seat. 0 = Lowermost.