Display name vocabulary term

[korygin]

Hello,

Are there any plans to define a standard vocabulary term for adding display name annotations to CSDL schema elements, such as properties, parameters, etc.? This seems to be a common issue OData APIs often have to address.

Thanks,

Alex Korygin

[ralfhandl]

Hi Alex,

for API doumentation you can use Core.Description and Core.LongDescription.

Data visualization is a trickier topic, and depending on the concrete use cases the demand for annotations quickly diverges. Have a look at the SAP vocabularies SAP Common (which defines "Label", "QuickInfo", and much more) and SAP UI (which defines "Chart", "KPI", and also much more 😄) to see how complex this can quickly get, and whether you can find much beyond "Label" that could be standardized across multiple companies and software products.

Thanks
Ralf

[korygin]

Thanks, Ralf. I know very well how complex this can get. We also have our own vocabularies and even extended protocols defined on top of OData. Our vocabulary terms vary from primitive to complex types, their values can be static or resolved dynamically from the payload at run-time.
One of the things that we found consistent across multiple products though is the requirement to provide the display names / labels as well as the ability to logically group properties for displaying in UI widgets such as property grids. So I thought I would ask about the former since it appears to be a simpler case. :)

[ralfhandl]

Yes, Common.Label and UI.FieldGroup were among the first terms we added. Yet even grouping properties isn't enough: just one grouping level, or subgroups? Just grid layout, or more closely grouped properties with group-specific arrangement? And so on.

That leaves the "label" / "display name" / "title" as the only candidate for a standard term...

[korygin]

Thanks again. It may be possible to define a vocabulary term that would support both: flat and hierarchical property groups, it doesn't have to be as primitive. Some of our products actually do have to integrate with SAP. It would be nice if the client could use a consistent set of vocabulary terms to build its representation regardless of what service it connects to. After all, the majority if not all UI clients have a very common set of components for data representation: forms, tables / grids, property groups, info maps, etc. So I thought it could be worth to at least give it a try starting with something small like display name / label and go from there. I feel I am steering into a philosophical type of discussion here... 😊 Anyways, it looks like what you are saying is that it is very hard if not impossible to define a common set of vocabulary terms for display purposes because the requirements across organizations and products are vastly different. Am I interpreting your answer correctly? Cheers, Alex

…

________________________________ From: Ralf Handl <notifications@github.com> Sent: Tuesday, September 18, 2018 11:09 AM To: oasis-tcs/odata-vocabularies Cc: Alex Korygin; Author Subject: Re: [oasis-tcs/odata-vocabularies] Display name vocabulary term (#20) Yes, Common.Label and UI.FieldGroup were among the first terms we added. Yet even grouping properties isn't enough: just one grouping level, or subgroups? Just grid layout, or more closely grouped properties with group-specific arrangement? And so on. That leaves the "label" / "display name" / "title" as the only candidate for a standard term... — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub<#20 (comment)>, or mute the thread<https://github.com/notifications/unsubscribe-auth/ANbNQodbjWcIAem8OmP0Cdj9iIY8GZLYks5ucRq0gaJpZM4Wsept>.

[ralfhandl]

Hi Alex,

Yes, it would be a hard journey to get to an agreed and useful display/UI vocabulary. And it would be useful for others if we invest the time. After all we managed to get a standard Capabilities vocabulary going.

As you have your display vocabulary and have access to SAP's UI vocabulary you could go ahead and try to extract a common subset. If that works out, we can discuss on how to get to a standard vocabulary.

Would that work for you?

Thanks in advance
Ralf

[korygin]

Hi Ralf, Sure, I can take a pass at it. It’s timely actually because we were planning the next sprint today and I added a story for myself. 😊 I’ll be back with the list. Thanks! Alex On Sep 19, 2018, at 11:46, Ralf Handl <notifications@github.com<mailto:notifications@github.com>> wrote: Hi Alex, Yes, it would be a hard journey to get to an agreed and useful display/UI vocabulary. And it would be useful for others if we invest the time. After all we managed to get a standard Capabilities vocabulary going. As you have your display vocabulary and have access to SAP's UI vocabulary<https://wiki.scn.sap.com/wiki/display/EmTech/OData+4.0+Vocabularies+-+SAP+UI> you could go ahead and try to extract a common subset. If that works out, we can discuss on how to get to a standard vocabulary. Would that work for you? Thanks in advance Ralf — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub<#20 (comment)>, or mute the thread<https://github.com/notifications/unsubscribe-auth/ANbNQtA4nuYF9Y0op0YOAcJdgPfjE_W-ks5ucmbhgaJpZM4Wsept>.

[korygin]

Hi Ralf, Here is the first pass. Please let me know if you have questions. Thanks! Alex Common vocabulary (com.sap.vocabularies.Common.v1) * Label and Heading - these two seem to be interchangeable, no? Also, do we need a more generic term such as DisplayName that can be added to other schema elements such as types? * Text - not clear what it is for exactly, need a clarification on the following statement: "Value MUST be a dynamic expression when used as metadata annotation". * ValueList - a very common concept. However, our case is a bit more complicated because our value lists are often hierarchical. That means the selection made in a parent list determines available values in its children (descendants). It also implies there are declarative dependencies between value list properties. We also have Title vocabulary term for the representation of a single OData resource instance on a graphical UI such as info map. Its value is the path to a property that provides a value that must be displayed on a graphical object, i.e. order number, inventory tag, document name, etc. UI vocabulary (com.sap.vocabularies.UI.v1) * HeaderInfo - it appears that at least some of the information specified in this annotation may come from other sources. For example, a common DisplayName annotation can be used in place of TypeName. The TypeNamePlural may come from DisplayName annotation placed on the corresponding resource set (collection). Description may come from Core.Description annotation. I like the concept of image URLs but I also think it's very much possible that the instance's value could be a property path, not just hard-coded URL string. * FieldGroup - I think we already discussed the potential need for supporting hierarchical property groups. * MultiLineText * Hidden

…

________________________________ From: Ralf Handl <notifications@github.com> Sent: Wednesday, September 19, 2018 10:46 AM To: oasis-tcs/odata-vocabularies Cc: Alex Korygin; Author Subject: Re: [oasis-tcs/odata-vocabularies] Display name vocabulary term (#20) Hi Alex, Yes, it would be a hard journey to get to an agreed and useful display/UI vocabulary. And it would be useful for others if we invest the time. After all we managed to get a standard Capabilities vocabulary going. As you have your display vocabulary and have access to SAP's UI vocabulary<https://wiki.scn.sap.com/wiki/display/EmTech/OData+4.0+Vocabularies+-+SAP+UI> you could go ahead and try to extract a common subset. If that works out, we can discuss on how to get to a standard vocabulary. Would that work for you? Thanks in advance Ralf — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub<#20 (comment)>, or mute the thread<https://github.com/notifications/unsubscribe-auth/ANbNQtA4nuYF9Y0op0YOAcJdgPfjE_W-ks5ucmbhgaJpZM4Wsept>.

[ralfhandl]

Hi Alex,

That seems to be a good starting point. Below some explanations on why we did what we did.

Looking forward to your comments
Ralf

Remarks

• Label can be added to any schema element. Heading is a special case for use in table column headers, and I'd rather have just one term in a standard vocabulary, e.g. DisplayName.

• Text is to pair a "code/id" property to a corresponding string property containing a text for the code/id, e.g. CountryCode and CountryName.

• ValueList: simple hierarchical dependency, e.g. Country - City, is covered by having multiple In or InOut parameters. Say a form contains a Country and a City input field, then the ValueList for City could point to an entity set with both fields in it, and have InOut parameters for Country and City. If a user has already filled in a Country, then the value list popup would only show cities for that country. If the Country field is empty, all cities would be shown, and picking a city would also fill the country field.

• Title: that can be useful as a separate term, we've rolled it into HeaderInfo/Title.

• HeaderInfo: yes, you can slice that in n different ways, one of the reasons why coming up with a standardized Display vocabulary is difficult 😄. The URLs typically are Path expressions pointing to a string property containing the URL.

• FieldGroup: this is intentionally flat and represents a "mini form". Groups of groups we do via the Facet annotation: a collection facet contains multiple reference facets, each of which reference a field group. Reference facets can also reference charts, tables, ..., and you can nest the collection facets arbitrarily deep. Think of facets as a tree of nested "frames" whose leafs are then filled with concrete stuff. This allows grouping a chart with a list, grouping that group with a form, grouping that group with ....
  Took some discussion to come up with that separation of "group/frame inner node" and "concrete leaf node", and similar discussions in other organizations may very well come up with something completely different.

[korygin]

Hi Ralf,

• Label - I agree that just one DisplayName term would be better

• Text - it's a property path, isn't it? The thing that confused me was that the term's type is declared as Edm.String rather than Edm.PropertyPath.

• ValueList - so, if I understand it correctly, both parent and child values are expected to be present in the same resource set (collection). If that's the case then the list is really "flat". It may be impossible to flatten some of our value lists because we have lists with an arbitrary hierarchy depth, some with as many as thousands of items. Also, our value lists can be exposed as contained entity sets, meaning in order to get to the list the client really needs to know predecessor(s) key(s). Another question would be how the client knows what form field needs to be updated based on selection made at the upper level of hierarchy if there is more than one input bound to the same list. For example, suppose there is a form with 4 drop-downs: Origin Country / Origin City and Destination Country / Destination City - all bound to the same list. If a new selection is made in Origin Country drop-down, how does the client know that only Origin City drop-down needs to be updated with the new list of cities, but not Destination City?

• Title - again we are in agreement that a separate term may be useful.

• HeaderInfo - I was just trying to avoid duplication. :) If an entity type has the header info with description and at the same time the core description annotation, which one should the client consider?

Thanks!

Alex

[korygin]

Hi Ralf,

Have there been any progress on the display vocabulary? Is there anything else I can help with to get this thing off the ground?

Thanks,

Alex

[ralfhandl]

Hi Alex,

Sorry, we are currently busy with finalizing OData Version 4.01, so no progress on this topic.

Thanks
Ralf