Nested attributes for Collection Types

[grv]

Hey Guys,

While working on OpenApi integration as well as GraphQL implementation, I
faced issues on how to automatically document request/response JSON
structure for service attributes that were of Collection types (Map, List
etc).

For simple types, it is just plain easy but when it comes to Map/Lists, you
have to know what exactly is inside them to be able to convey properly in
the OpenApi schema.

I was thinking to may be try to introduce nested attributes in service
definition such that if the attribute type is Map/List, you can actually
specify what goes inside that attribute -

<attribute name=*"header"* type=*"Map"* mode=*"IN"* optional=*"true"* >

    <attribute name=*"xy"* type=*"Integer"*  default-value=*"0"* />

    <attribute name=*"xyz"* type=*"String"*  default-value=*"test"*/>

</attribute>



With this change, it becomes possible to generate the schema for the
service attribute, Where as if we don't have this option, we can't possibly
indicate what the structure of the "header" key is going to be if it was
represented in JSON format.

Of course, this change will only help documentation and GraphQL
implementation and that there is very little case for it to benefit a
general OFBiz service call.

Any thoughts or comments on this? Is this too big of a change (impact wise
and not coding perspective) to avoid it and consider something else? Has
this been discussed before?

Best,
Girish

[Pritam Kute]

Hello Girish,

IMO, the option which you have suggested looks good in case if we want to
leverage upon the existing service definitions for creating the API
documentation. I also think that this could be a good addition to OFBiz in
the developer perspective, as right now, it is very difficult to guess the
content of the Map/List attributes seeing at service definition. For the
attribute type GenericValue, we can skip the nested structure.

Kind Regards,
--
Pritam Kute


On Thu, Jul 16, 2020 at 5:21 PM Girish Vasmatkar <
[hidden email]> wrote:

> Hey Guys,
>
> While working on OpenApi integration as well as GraphQL implementation, I
> faced issues on how to automatically document request/response JSON
> structure for service attributes that were of Collection types (Map, List
> etc).
>
> For simple types, it is just plain easy but when it comes to Map/Lists, you
> have to know what exactly is inside them to be able to convey properly in
> the OpenApi schema.
>
> I was thinking to may be try to introduce nested attributes in service
> definition such that if the attribute type is Map/List, you can actually
> specify what goes inside that attribute -
>
> <attribute name=*"header"* type=*"Map"* mode=*"IN"* optional=*"true"* >
>
>     <attribute name=*"xy"* type=*"Integer"*  default-value=*"0"* />
>
>     <attribute name=*"xyz"* type=*"String"*  default-value=*"test"*/>
>
> </attribute>
>
>
>
> With this change, it becomes possible to generate the schema for the
> service attribute, Where as if we don't have this option, we can't possibly
> indicate what the structure of the "header" key is going to be if it was
> represented in JSON format.
>
> Of course, this change will only help documentation and GraphQL
> implementation and that there is very little case for it to benefit a
> general OFBiz service call.
>
> Any thoughts or comments on this? Is this too big of a change (impact wise
> and not coding perspective) to avoid it and consider something else? Has
> this been discussed before?
>
> Best,
> Girish
>

[Jacques Le Roux]

Hi Girish,

I don't remember this having been discussed before. I like the idea and the proposed "implementation".
I don't think it's a too big change, it's an improvement for me.

About Pritam's remark for GenericValue, if it may help: those are Maps [Map<String, Object>] and considered  as such in SOAP.

Thanks

Jacques

Le 17/07/2020 à 07:21, Pritam Kute a écrit :

> Hello Girish,
>
> IMO, the option which you have suggested looks good in case if we want to
> leverage upon the existing service definitions for creating the API
> documentation. I also think that this could be a good addition to OFBiz in
> the developer perspective, as right now, it is very difficult to guess the
> content of the Map/List attributes seeing at service definition. For the
> attribute type GenericValue, we can skip the nested structure.
>
> Kind Regards,
> --
> Pritam Kute
>
>
> On Thu, Jul 16, 2020 at 5:21 PM Girish Vasmatkar <
> [hidden email]> wrote:
>
>> Hey Guys,
>>
>> While working on OpenApi integration as well as GraphQL implementation, I
>> faced issues on how to automatically document request/response JSON
>> structure for service attributes that were of Collection types (Map, List
>> etc).
>>
>> For simple types, it is just plain easy but when it comes to Map/Lists, you
>> have to know what exactly is inside them to be able to convey properly in
>> the OpenApi schema.
>>
>> I was thinking to may be try to introduce nested attributes in service
>> definition such that if the attribute type is Map/List, you can actually
>> specify what goes inside that attribute -
>>
>> <attribute name=*"header"* type=*"Map"* mode=*"IN"* optional=*"true"* >
>>
>>      <attribute name=*"xy"* type=*"Integer"*  default-value=*"0"* />
>>
>>      <attribute name=*"xyz"* type=*"String"*  default-value=*"test"*/>
>>
>> </attribute>
>>
>>
>>
>> With this change, it becomes possible to generate the schema for the
>> service attribute, Where as if we don't have this option, we can't possibly
>> indicate what the structure of the "header" key is going to be if it was
>> represented in JSON format.
>>
>> Of course, this change will only help documentation and GraphQL
>> implementation and that there is very little case for it to benefit a
>> general OFBiz service call.
>>
>> Any thoughts or comments on this? Is this too big of a change (impact wise
>> and not coding perspective) to avoid it and consider something else? Has
>> this been discussed before?
>>
>> Best,
>> Girish
>>

[Mridul Pathak-4]

Hi Girish,

I think this would be a good improvement to service definition. While it makes more sense that it would enable creating JSON like schema definitions it would make service definitions more predictable in general. This improvement could also be applied to existing service definitions to be able to expose them as an API in a more sensible way.

Thanks.
--
Mridul Pathak

> On 16-Jul-2020, at 5:20 PM, Girish Vasmatkar <[hidden email]> wrote:
>
> Hey Guys,
>
> While working on OpenApi integration as well as GraphQL implementation, I
> faced issues on how to automatically document request/response JSON
> structure for service attributes that were of Collection types (Map, List
> etc).
>
> For simple types, it is just plain easy but when it comes to Map/Lists, you
> have to know what exactly is inside them to be able to convey properly in
> the OpenApi schema.
>
> I was thinking to may be try to introduce nested attributes in service
> definition such that if the attribute type is Map/List, you can actually
> specify what goes inside that attribute -
>
> <attribute name=*"header"* type=*"Map"* mode=*"IN"* optional=*"true"* >
>
>    <attribute name=*"xy"* type=*"Integer"*  default-value=*"0"* />
>
>    <attribute name=*"xyz"* type=*"String"*  default-value=*"test"*/>
>
> </attribute>
>
>
>
> With this change, it becomes possible to generate the schema for the
> service attribute, Where as if we don't have this option, we can't possibly
> indicate what the structure of the "header" key is going to be if it was
> represented in JSON format.
>
> Of course, this change will only help documentation and GraphQL
> implementation and that there is very little case for it to benefit a
> general OFBiz service call.
>
> Any thoughts or comments on this? Is this too big of a change (impact wise
> and not coding perspective) to avoid it and consider something else? Has
> this been discussed before?
>
> Best,
> Girish

[Jacques Le Roux]

Thanks Mridul,

I agree about enhancing existing service definitions

Jacques

Le 20/07/2020 à 10:37, Mridul Pathak a écrit :

> Hi Girish,
>
> I think this would be a good improvement to service definition. While it makes more sense that it would enable creating JSON like schema definitions it would make service definitions more predictable in general. This improvement could also be applied to existing service definitions to be able to expose them as an API in a more sensible way.
>
> Thanks.
> --
> Mridul Pathak
>
>
>> On 16-Jul-2020, at 5:20 PM, Girish Vasmatkar <[hidden email]> wrote:
>>
>> Hey Guys,
>>
>> While working on OpenApi integration as well as GraphQL implementation, I
>> faced issues on how to automatically document request/response JSON
>> structure for service attributes that were of Collection types (Map, List
>> etc).
>>
>> For simple types, it is just plain easy but when it comes to Map/Lists, you
>> have to know what exactly is inside them to be able to convey properly in
>> the OpenApi schema.
>>
>> I was thinking to may be try to introduce nested attributes in service
>> definition such that if the attribute type is Map/List, you can actually
>> specify what goes inside that attribute -
>>
>> <attribute name=*"header"* type=*"Map"* mode=*"IN"* optional=*"true"* >
>>
>>     <attribute name=*"xy"* type=*"Integer"*  default-value=*"0"* />
>>
>>     <attribute name=*"xyz"* type=*"String"*  default-value=*"test"*/>
>>
>> </attribute>
>>
>>
>>
>> With this change, it becomes possible to generate the schema for the
>> service attribute, Where as if we don't have this option, we can't possibly
>> indicate what the structure of the "header" key is going to be if it was
>> represented in JSON format.
>>
>> Of course, this change will only help documentation and GraphQL
>> implementation and that there is very little case for it to benefit a
>> general OFBiz service call.
>>
>> Any thoughts or comments on this? Is this too big of a change (impact wise
>> and not coding perspective) to avoid it and consider something else? Has
>> this been discussed before?
>>
>> Best,
>> Girish

[grv]

Thank you, all. I've created
https://issues.apache.org/jira/browse/OFBIZ-11902 to track this.

Best,
Girish

On Tue, Jul 21, 2020 at 1:14 AM Jacques Le Roux <
[hidden email]> wrote:

> Thanks Mridul,
>
> I agree about enhancing existing service definitions
>
> Jacques
>
> Le 20/07/2020 à 10:37, Mridul Pathak a écrit :
> > Hi Girish,
> >
> > I think this would be a good improvement to service definition. While it
> makes more sense that it would enable creating JSON like schema definitions
> it would make service definitions more predictable in general. This
> improvement could also be applied to existing service definitions to be
> able to expose them as an API in a more sensible way.
> >
> > Thanks.
> > --
> > Mridul Pathak
> >
> >
> >> On 16-Jul-2020, at 5:20 PM, Girish Vasmatkar <
> [hidden email]> wrote:
> >>
> >> Hey Guys,
> >>
> >> While working on OpenApi integration as well as GraphQL implementation,
> I
> >> faced issues on how to automatically document request/response JSON
> >> structure for service attributes that were of Collection types (Map,
> List
> >> etc).
> >>
> >> For simple types, it is just plain easy but when it comes to Map/Lists,
> you
> >> have to know what exactly is inside them to be able to convey properly
> in
> >> the OpenApi schema.
> >>
> >> I was thinking to may be try to introduce nested attributes in service
> >> definition such that if the attribute type is Map/List, you can actually
> >> specify what goes inside that attribute -
> >>
> >> <attribute name=*"header"* type=*"Map"* mode=*"IN"* optional=*"true"* >
> >>
> >>     <attribute name=*"xy"* type=*"Integer"*  default-value=*"0"* />
> >>
> >>     <attribute name=*"xyz"* type=*"String"*  default-value=*"test"*/>
> >>
> >> </attribute>
> >>
> >>
> >>
> >> With this change, it becomes possible to generate the schema for the
> >> service attribute, Where as if we don't have this option, we can't
> possibly
> >> indicate what the structure of the "header" key is going to be if it was
> >> represented in JSON format.
> >>
> >> Of course, this change will only help documentation and GraphQL
> >> implementation and that there is very little case for it to benefit a
> >> general OFBiz service call.
> >>
> >> Any thoughts or comments on this? Is this too big of a change (impact
> wise
> >> and not coding perspective) to avoid it and consider something else? Has
> >> this been discussed before?
> >>
> >> Best,
> >> Girish
>
>