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.