Adding JSON output to the webservice

classic Classic list List threaded Threaded
12 messages Options
Reply | Threaded
Open this post in threaded view
|

Adding JSON output to the webservice

Kuno Woudt

Hello developers!

I have started / resumed work on the json serialization of our
webservice [1].

My goal for the json webservice is to keep most of the structure of the
XML, but make small changes where neccesary to express things in a form
more suited for json.

I have documented my proposed serialization using examples which should
cover all entities and their properties:

http://wiki.musicbrainz.org/User:kuno/Web_Service/JSON

If you're interested in a JSON webservice, please have a look at this
document and let me know if something seems wrong.  Come talk to me on
irc [2] or respond here on the mailing list with your feedback.

Thanks!

-- kuno / warp.

[1] http://tickets.musicbrainz.org/browse/MBS-3072
[2] #musicbrainz-devel on freenode irc


_______________________________________________
MusicBrainz-devel mailing list
[hidden email]
http://lists.musicbrainz.org/mailman/listinfo/musicbrainz-devel
Reply | Threaded
Open this post in threaded view
|

Re: Adding JSON output to the webservice

Paul Taylor-2
On 06/07/2012 17:36, Kuno Woudt wrote:
Hello developers!

I have started / resumed work on the json serialization of our 
webservice [1].

My goal for the json webservice is to keep most of the structure of the 
XML, but make small changes where neccesary to express things in a form 
more suited for json.

I have documented my proposed serialization using examples which should 
cover all entities and their properties:

http://wiki.musicbrainz.org/User:kuno/Web_Service/JSON

If you're interested in a JSON webservice, please have a look at this 
document and let me know if something seems wrong.  Come talk to me on 
irc [2] or respond here on the mailing list with your feedback.
Kuno

1. I have a question about the pluralising of array element

i.e
tag to tags
alias to aliases

Is this normal practise to pluralise array elements in Json, doesn't the fact that there is an array make this obvious

I ask because I think we should only change things if they are not look right for Json, to reduce divergence form the XMl to the minimum.

2. Removal of name-credit for artist credit

Comparing
<artist-credit>
<name-credit joinphrase=" feat. ">
<artist id="455641ea-fff4-49f6-8fb4-49f961d8f1ac">
<name>倖田來未</name>
<sort-name>Koda, Kumi</sort-name>
</artist>
</name-credit>
<name-credit>
<artist id="05cbaf37-6dc2-4f71-a0ce-d633447d90c3">
<name>東方神起</name>
<sort-name>TVXQ</sort-name>
</artist>
</name-credit>
</artist-credit>

with

"artist-credit": [
        {
            "name": "\u6771\u65b9\u795e\u8d77",
            "joinphrase": " feat. ",
            "artist": {
                "id": "455641ea-fff4-49f6-8fb4-49f961d8f1ac",
                "name": "\u6771\u65b9\u795e\u8d77",
                "sort-name": "Koda, Kumi"
            }
        },
        {
            "name": "\u5016\u7530\u4f86\u672a",
            "artist": {
                "id": "05cbaf37-6dc2-4f71-a0ce-d633447d90c3",
                "name": "\u5016\u7530\u4f86\u672a",
                "sort-name": "TVXQ"
            }
        }
    ],

The json has a name-credit element but gains a name-credit id field
"name": "\u6771\u65b9\u795e\u8d77",

why is this added ?

3. Relationships

I couldn't see an example showing the relationship changes


Paul

Thanks!

-- kuno / warp.

[1] http://tickets.musicbrainz.org/browse/MBS-3072
[2] #musicbrainz-devel on freenode irc


_______________________________________________
MusicBrainz-devel mailing list
[hidden email]
http://lists.musicbrainz.org/mailman/listinfo/musicbrainz-devel




_______________________________________________
MusicBrainz-devel mailing list
[hidden email]
http://lists.musicbrainz.org/mailman/listinfo/musicbrainz-devel
Reply | Threaded
Open this post in threaded view
|

Re: Adding JSON output to the webservice

Kuno Woudt
ref: http://wiki.musicbrainz.org/User:kuno/Web_Service/JSON


Hello Paul,

On 07/08/2012 01:58 AM, Paul Taylor wrote:

> 1. I have a question about the pluralising of array element
>
> i.e
> tag to tags
> alias to aliases
>
> Is this normal practise to pluralise array elements in Json, doesn't the
> fact that there is an array make this obvious
>
> I ask because I think we should only change things if they are not look
> right for Json, to reduce divergence form the XMl to the minimum.

The structure of these is already different from the XML, so it seemed
safe to me to change the name as well.

I don't think there is much of a convention for json itself.  But json
is typically consumed by deserializing it into a native structure.  I
think it is common practice to name sequences or collections of things
using a plural, so you can do things like:

for tag in tags:
    print (tag["name"])

This is just my impression though, as most style guidelines (e.g. PEP8
for python, the various PHP guides, etc...) do not mention a specific
naming convention for arrays/lists.

The two examples I did find are:
- http://ur1.ca/9qzsg (for java, from the eclipse people)
- http://ur1.ca/9qzsi (for javascript, from dojo toolkit)


> 2. Removal of name-credit for artist credit
>
> The json has a name-credit element but gains a name-credit id field
>
> "name": "\u6771\u65b9\u795e\u8d77",
>
> why is this added ?

It is only omitted in the XML because it happens to be the same as the
name inside the <artist> element.  You can think of the <name> in the
<name-credit> as overriding the <name> inside the <artist> element.

Although it sounds logical when explained like that, I think it is still
somewhat confusing and would prefer to always include it, which is what
I intend to do with the JSON.

Here is an XML example with both <name> elements included on the first
artist, Koda Kumi:

http://musicbrainz.org/ws/2/release/8ea5b78d-bda6-497a-b191-2650b8e20ba0?inc=artist-credits

> 3. Relationships
>
> I couldn't see an example showing the relationship changes
>

The only real change compared to the XML is that I get rid of the
separate lists.  In the XML you have:

<relation-list target-type="artist">
   <!-- all artist relations go here -->
</relation-list>
<relation-list target-type="recording">
   <!-- all recording relations go here -->
</relation-list>

Whereas in JSON I have combined those to be a single list:

"relations": [
   /* all types of relations go here */
]

The other change is that <target> is removed entirely, as it just
repeated information also available as the "id" property on the entity
element.  Well, except for url relationships, so I've renamed "target"
to "url" in that case:

<relation type="download for free">
 
<target>http://soundcloud.com/strictly/kraftwerk-kover-kollection-vol</target>
</relation>

{
     "type": "download for free",
     "url": "http://soundcloud.com/strictly/kraftwerk-kover-kollection-vol"
}

This makes it more consistent with the other relations, which all have
the entity name (recording, artist, etc..) as a key as well.

-- kuno / warp.

_______________________________________________
MusicBrainz-devel mailing list
[hidden email]
http://lists.musicbrainz.org/mailman/listinfo/musicbrainz-devel
Reply | Threaded
Open this post in threaded view
|

Re: Adding JSON output to the webservice

Paul Taylor-2
On 09/07/2012 09:24, Kuno Woudt wrote:

> ref: http://wiki.musicbrainz.org/User:kuno/Web_Service/JSON
>
>
> Hello Paul,
>
> On 07/08/2012 01:58 AM, Paul Taylor wrote:
>> 1. I have a question about the pluralising of array element
>>
>> i.e
>> tag to tags
>> alias to aliases
>>
>> Is this normal practise to pluralise array elements in Json, doesn't the
>> fact that there is an array make this obvious
>>
>> I ask because I think we should only change things if they are not look
>> right for Json, to reduce divergence form the XMl to the minimum.
> The structure of these is already different from the XML, so it seemed
> safe to me to change the name as well.
To quote

'My goal for the json webservice is to keep most of the structure of the
XML, but make small change'

I accept some changes need to be made to make it more json like, such as the removal of <valuelist> with an array. But I think any other changes should be reserved for ws/3, and then applied to both the json and the Xml output. from a practical point of view on the search server side of things both the json and xml can currenlty be generated from the one schema , this makes the code alot more maintainable and I think I have a solution to flatten the list part for Json but every additional change you make requires further modification/hacks to make it work.

If it is correct convention to pluralize list elements in json then I can try and work with it, but if the convention is just in the calling client code or other languages I don't think we should be doing this. Certainly the Java example doesnt match with what I normally do which is call a thing a list if it is a list, i.e <List> relationList releaseList = new ArrayList<Release>();
 

>
> I don't think there is much of a convention for json itself.  But json
> is typically consumed by deserializing it into a native structure.  I
> think it is common practice to name sequences or collections of things
> using a plural, so you can do things like:
>
> for tag in tags:
>      print (tag["name"])
>
> This is just my impression though, as most style guidelines (e.g. PEP8
> for python, the various PHP guides, etc...) do not mention a specific
> naming convention for arrays/lists.
>
> The two examples I did find are:
> - http://ur1.ca/9qzsg (for java, from the eclipse people)
> - http://ur1.ca/9qzsi (for javascript, from dojo toolkit)
>
>
>> 2. Removal of name-credit for artist credit
>>
>> The json has a name-credit element but gains a name-credit id field
>>
>> "name": "\u6771\u65b9\u795e\u8d77",
>>
>> why is this added ?
> It is only omitted in the XML because it happens to be the same as the
> name inside the <artist> element.  You can think of the <name> in the
> <name-credit> as overriding the <name> inside the <artist> element.
>
> Although it sounds logical when explained like that, I think it is still
> somewhat confusing and would prefer to always include it, which is what
> I intend to do with the JSON.
>
> Here is an XML example with both <name> elements included on the first
> artist, Koda Kumi:
>
> http://musicbrainz.org/ws/2/release/8ea5b78d-bda6-497a-b191-2650b8e20ba0?inc=artist-credits
Okay whether or not you always include an element even when its the
same, or missing is fine by me, not a concern. But I don't understand
why changing the name-credit element to an anoymous element (dont know
if that is the right terminology)   improves things, and I dont
understand why you have anyomised this one but no others ?

>> 3. Relationships
>>
>> I couldn't see an example showing the relationship changes
>>
> The only real change compared to the XML is that I get rid of the
> separate lists.  In the XML you have:
>
> <relation-list target-type="artist">
>     <!-- all artist relations go here -->
> </relation-list>
> <relation-list target-type="recording">
>     <!-- all recording relations go here -->
> </relation-list>
>
> Whereas in JSON I have combined those to be a single list:
>
> "relations": [
>     /* all types of relations go here */
> ]
I would say that makes things worse.
In my client code I iterate through particular types of relations, for
example I want to know if a release has a link to to a Discogs release
so I just get the relations of type url for the release and then iterate
through them. With this change you would have to iterate through all
relationships every time.

Paul

_______________________________________________
MusicBrainz-devel mailing list
[hidden email]
http://lists.musicbrainz.org/mailman/listinfo/musicbrainz-devel
Reply | Threaded
Open this post in threaded view
|

Re: Adding JSON output to the webservice

Kuno Woudt
ref: http://wiki.musicbrainz.org/User:kuno/Web_Service/JSON


Hello Paul,

On 07/09/2012 04:04 PM, Paul Taylor wrote:

> On 09/07/2012 09:24, Kuno Woudt wrote:
> To quote
>
> 'My goal for the json webservice is to keep most of the structure of
> the XML, but make small change'
>
> I accept some changes need to be made to make it more json like, such
> as the removal of <valuelist> with an array. But I think any other
> changes should be reserved for ws/3, and then applied to both the
> json and the Xml output. from a practical point of view on the search
> server side of things both the json and xml can currenlty be
> generated from the one schema , this makes the code alot more
> maintainable and I think I have a solution to flatten the list part
> for Json but every additional change you make requires further
> modification/hacks to make it work.
>
> If it is correct convention to pluralize list elements in json then I
> can try and work with it, but if the convention is just in the
> calling client code or other languages I don't think we should be
> doing this. Certainly the Java example doesnt match with what I
> normally do which is call a thing a list if it is a list, i.e <List>
> relationList releaseList = new ArrayList<Release>();

I could use the -list names again, so:

"tag-list": [
     { "count": 1, "name": "kpop" },
     { "count": 1, "name": "jpop" },
     { "count": 1, "name": "cpop" }
]

But that is still different from the search server json, which has:

"tag-list": {
   "tag": [
     { "count": 1, "name": "kpop" },
     { "count": 1, "name": "jpop" },
     { "count": 1, "name": "cpop" }
   ]
}

So, I assumed, because these are different things, and you will have to
hack this anyway, it wouldn't be much of an extra burden to patch the
name as well.

>>> 2. Removal of name-credit for artist credit
>>>
>> http://musicbrainz.org/ws/2/release/8ea5b78d-bda6-497a-b191-2650b8e20ba0?inc=artist-credits
>
>>
 > Okay whether or not you always include an element even when its the
> same, or missing is fine by me, not a concern. But I don't
> understand why changing the name-credit element to an anoymous
> element (dont know if that is the right terminology)   improves
> things, and I dont understand why you have anyomised this one but no
> others ?

I have done this elsewhere as well.  For example the "tag" element in
the example earlier in this e-mail.

The structure in the search server is this:

"artist-credit": {
   "name-credit": [
     { "name": "x", "joinphrase": "y", "artist": {} },
     { "name": "z", "joinphrase": "", "artist": {} }
   ]
}

So, the artist-credit object always contains exactly one "name-credit"
property, and nothing else.  This seems like a pointless indirection to me.

>>> 3. Relationships
>>>
>>> I couldn't see an example showing the relationship changes
>>>
>> The only real change compared to the XML is that I get rid of the
>> separate lists.  In the XML you have:
>>
>> <relation-list target-type="artist"> <!-- all artist relations go
>> here --> </relation-list> <relation-list target-type="recording">
>> <!-- all recording relations go here --> </relation-list>
>>
>> Whereas in JSON I have combined those to be a single list:
>>
>> "relations": [ /* all types of relations go here */ ]
> I would say that makes things worse. In my client code I iterate
> through particular types of relations, for example I want to know if
> a release has a link to to a Discogs release so I just get the
> relations of type url for the release and then iterate through them.
> With this change you would have to iterate through all relationships
> every time.

Are you worried about performance or code clarity?

To me the json output seemed easier to understand if it's just a single
list.  If you want to query that list for specific relationships that
seems like something which the client should do.

If you only want certain types just filter the list.

e.g. in python:

filter (lambda rel: "artist" in rel, json["relations"])

or in javascript with underscore.js:

_(json["relations"]).filter (function (rel) { return rel.artist })

I guess in java it would get a bit more verbose.


Still, I guess it is a common use case, and I'll consider it if more
people object to a single list.  Would you be happy with the structure
like this?:

"relations": {
   "artist": [
     { "direction": "backward", "type": "composer", "artist": {} },
     { "direction": "backward", "type": "lyricist", "artist": {} }
   ],
   "recording": [
     { "direction": "backward", "type": "performance", "recording": {} },
     { "direction": "backward", "type": "performance", "recording": {} },
   ]
}


-- kuno / warp.

_______________________________________________
MusicBrainz-devel mailing list
[hidden email]
http://lists.musicbrainz.org/mailman/listinfo/musicbrainz-devel
Reply | Threaded
Open this post in threaded view
|

Re: Adding JSON output to the webservice

Paul Taylor-2
On 09/07/2012 18:29, Kuno Woudt wrote:
ref: http://wiki.musicbrainz.org/User:kuno/Web_Service/JSON


Hello Paul,

On 07/09/2012 04:04 PM, Paul Taylor wrote:
On 09/07/2012 09:24, Kuno Woudt wrote:
To quote

'My goal for the json webservice is to keep most of the structure of
the XML, but make small change'

I accept some changes need to be made to make it more json like, such
as the removal of <valuelist> with an array. But I think any other
changes should be reserved for ws/3, and then applied to both the
json and the Xml output. from a practical point of view on the search
server side of things both the json and xml can currenlty be
generated from the one schema , this makes the code alot more
maintainable and I think I have a solution to flatten the list part
for Json but every additional change you make requires further
modification/hacks to make it work.

If it is correct convention to pluralize list elements in json then I
can try and work with it, but if the convention is just in the
calling client code or other languages I don't think we should be
doing this. Certainly the Java example doesnt match with what I
normally do which is call a thing a list if it is a list, i.e <List>
relationList releaseList = new ArrayList<Release>();
I could use the -list names again, so:

"tag-list": [
     { "count": 1, "name": "kpop" },
     { "count": 1, "name": "jpop" },
     { "count": 1, "name": "cpop" }
]

But that is still different from the search server json, which has:

"tag-list": {
   "tag": [
     { "count": 1, "name": "kpop" },
     { "count": 1, "name": "jpop" },
     { "count": 1, "name": "cpop" }
   ]
}

So, I assumed, because these are different things, and you will have to 
hack this anyway, it wouldn't be much of an extra burden to patch the 
name as well.
I think I have a solution to do this in a structured way, see the answer about Moxy http://stackoverflow.com/questions/10699038/generating-more-json-like-json-from-jaxb-and-jersey

to give me

"tag": [
     { "count": 1, "name": "kpop" },
     { "count": 1, "name": "jpop" },
     { "count": 1, "name": "cpop" }
]

which looks good json to me

But I don't have a good solution to change tag to tags, so it a burden, if it needs to be tags rather than tag I can find a solution , but if there is no good reason for changing tags to tag then why do it ?



      
2. Removal of name-credit for artist credit

http://musicbrainz.org/ws/2/release/8ea5b78d-bda6-497a-b191-2650b8e20ba0?inc=artist-credits

        

        
 > Okay whether or not you always include an element even when its the
same, or missing is fine by me, not a concern. But I don't
understand why changing the name-credit element to an anoymous
element (dont know if that is the right terminology)   improves
things, and I dont understand why you have anyomised this one but no
others ?
I have done this elsewhere as well.  For example the "tag" element in 
the example earlier in this e-mail.
It seems  different to me , youv'e lost tag-list and replaced it with an array. That is fine because json has an array type and xml does not. But in this case you have replaced name-credit with anonymous list rather than replaced artist-credit-list. Maybe the problem is that the xml should have been:

<artist-credit-list>
<artist-credit joinphrase=" feat. ">
<artist id="455641ea-fff4-49f6-8fb4-49f961d8f1ac">
<name>倖田來未</name>
<sort-name>Koda, Kumi</sort-name>
</artist>
</artist-credit>
<artist-credit>
<artist id="05cbaf37-6dc2-4f71-a0ce-d633447d90c3">
<name>東方神起</name>
<sort-name>TVXQ</sort-name>
</artist>
</artist-credit>
</artist-credit>

and then I could see the json being

 "artist-credit": [
        {
            "name": "\u6771\u65b9\u795e\u8d77",
            "joinphrase": " feat. ",
            "artist": {
                "id": "455641ea-fff4-49f6-8fb4-49f961d8f1ac",
                "name": "\u6771\u65b9\u795e\u8d77",
                "sort-name": "Koda, Kumi"
            }
        },
        {
            "name": "\u5016\u7530\u4f86\u672a",
            "artist": {
                "id": "05cbaf37-6dc2-4f71-a0ce-d633447d90c3",
                "name": "\u5016\u7530\u4f86\u672a",
                "sort-name": "TVXQ"
            }
        }
    ],
but if there is a concept of name-credit distinct to artist-credit, it shouldn't be anonymised. If it is invalid concept to start with then it needs fixing in the xml in ws/3
The structure in the search server is this:

"artist-credit": {
   "name-credit": [
     { "name": "x", "joinphrase": "y", "artist": {} },
     { "name": "z", "joinphrase": "", "artist": {} }
   ]
}

So, the artist-credit object always contains exactly one "name-credit" 
property, and nothing else.  This seems like a pointless indirection to me.

3. Relationships

I couldn't see an example showing the relationship changes

The only real change compared to the XML is that I get rid of the
separate lists.  In the XML you have:

<relation-list target-type="artist"> <!-- all artist relations go
here --> </relation-list> <relation-list target-type="recording">
<!-- all recording relations go here --> </relation-list>

Whereas in JSON I have combined those to be a single list:

"relations": [ /* all types of relations go here */ ]
I would say that makes things worse. In my client code I iterate
through particular types of relations, for example I want to know if
a release has a link to to a Discogs release so I just get the
relations of type url for the release and then iterate through them.
With this change you would have to iterate through all relationships
every time.
Are you worried about performance or code clarity?
Both really, we have reduced the structure reducing code clarity, and filtering a load of relationships is going to be slower than just filtering/iterating relationships that have already been subgrouped
into types.

To me the json output seemed easier to understand if it's just a single 
list.  If you want to query that list for specific relationships that 
seems like something which the client should do.

If you only want certain types just filter the list.

e.g. in python:

filter (lambda rel: "artist" in rel, json["relations"])

or in javascript with underscore.js:

_(json["relations"]).filter (function (rel) { return rel.artist })

I guess in java it would get a bit more verbose.


Still, I guess it is a common use case, and I'll consider it if more
people object to a single list.  Would you be happy with the structure 
like this?:

"relations": {
   "artist": [
     { "direction": "backward", "type": "composer", "artist": {} },
     { "direction": "backward", "type": "lyricist", "artist": {} }
   ],
   "recording": [
     { "direction": "backward", "type": "performance", "recording": {} },
     { "direction": "backward", "type": "performance", "recording": {} },
   ]
}

I thinks so, how does that differ from what we have ?

Paul

_______________________________________________
MusicBrainz-devel mailing list
[hidden email]
http://lists.musicbrainz.org/mailman/listinfo/musicbrainz-devel
Reply | Threaded
Open this post in threaded view
|

Re: Adding JSON output to the webservice

Kuno Woudt
ref: http://wiki.musicbrainz.org/User:kuno/Web_Service/JSON


On 07/09/2012 10:27 PM, Paul Taylor wrote:

> On 09/07/2012 18:29, Kuno Woudt wrote:
>> ref:http://wiki.musicbrainz.org/User:kuno/Web_Service/JSON
>>
>> I could use the -list names again, so:
>>
>> "tag-list": [
>>       { "count": 1, "name": "kpop" },
>>       { "count": 1, "name": "jpop" },
>>       { "count": 1, "name": "cpop" }
>> ]
>>
>> But that is still different from the search server json, which has:
>>
>> "tag-list": {
>>     "tag": [
>>       { "count": 1, "name": "kpop" },
>>       { "count": 1, "name": "jpop" },
>>       { "count": 1, "name": "cpop" }
>>     ]
>> }
>>
>> So, I assumed, because these are different things, and you will have to
>> hack this anyway, it wouldn't be much of an extra burden to patch the
>> name as well.
> I think I have a solution to do this in a structured way, see the answer
> about Moxy
> http://stackoverflow.com/questions/10699038/generating-more-json-like-json-from-jaxb-and-jersey
>
> to give me
>
> "tag": [
>       { "count": 1, "name": "kpop" },
>       { "count": 1, "name": "jpop" },
>       { "count": 1, "name": "cpop" }
> ]
>
>
> which looks good json to me
>
> But I don't have a good solution to change tag to tags, so it a burden,
> if it needs to be tags rather than tag I can find a solution , but if
> there is no good reason for changing tags to tag then why do it ?

Just "tag" is wrong, it's not a tag, it is a list of tags.  So the key
should either be "tags" or "tag-list" (or something similar).


>>>>> 2. Removal of name-credit for artist credit
>>>>>
>>>> http://musicbrainz.org/ws/2/release/8ea5b78d-bda6-497a-b191-2650b8e20ba0?inc=artist-credits
>>   > Okay whether or not you always include an element even when its the
>>> same, or missing is fine by me, not a concern. But I don't
>>> understand why changing the name-credit element to an anoymous
>>> element (dont know if that is the right terminology)   improves
>>> things, and I dont understand why you have anyomised this one but no
>>> others ?
>> I have done this elsewhere as well.  For example the "tag" element in
>> the example earlier in this e-mail.
> It seems  different to me , youv'e lost tag-list and replaced it with an
> array. That is fine because json has an array type and xml does not. But
> in this case you have replaced name-credit with anonymous list rather
> than replaced artist-credit-list.

An artist credit is already a list.

> but if there is a concept of name-credit distinct to artist-credit, it
> shouldn't be anonymised. If it is invalid concept to start with then it
> needs fixing in the xml in ws/3

In the database and the perl data model the individual items are called
"artist credit name", those end up in the XML as name-credit.  So, an
artist credit is a list of artist credit names, aka name credits.  But I
don't think an artist credit name in itself is a separate concept, it
just has a name in the database because database tables must have names,
it has a name in the XML because you need to group this stuff in
_something_, and that something needs to have a name.  The concept we're
describing is an artist credit as a whole, and it seems perfectly
natural to not give the individual items in an artist credit a name in
the json output.

As a sidenote, in earlier versions of the perl code base these were
serialized internally like this:

"artist-credit": [
   {
      "name": "foo",
      "artist": { "name": "The Foo" }
   },
   " feat. ",
   {
      "name": "bar",
      "artist": { "name": "DJ Bar" }
   }
]

Which was quite confusing to work with :), but I think illustrates that
the name credits are not a concept in themselves, but an implementation
detail.

>>>>> 3. Relationships
>>
>> Still, I guess it is a common use case, and I'll consider it if more
>> people object to a single list.  Would you be happy with the structure
>> like this?:
>>
>> "relations": {
>>     "artist": [
>>       { "direction": "backward", "type": "composer", "artist": {} },
>>       { "direction": "backward", "type": "lyricist", "artist": {} }
>>     ],
>>     "recording": [
>>       { "direction": "backward", "type": "performance", "recording": {} },
>>       { "direction": "backward", "type": "performance", "recording": {} },
>>     ]
>> }
>>

The search server has:

"relation-list": [
  {
    "target-type": "artist",
    "relation": [
       { "direction": "backward", "type": "composer", "artist": {} },
       { "direction": "backward", "type": "lyricist", "artist": {} }
    ]
  },
  {
    "target-type": "recording",
    "relation": [
       { "direction": "backward", "type": "performance", "recording": {} },
       { "direction": "backward", "type": "performance", "recording": {} }
    ]
  }
]

The value of "target-type" would be moved to be a key.  So that you
can just do  data["relation-list"]["artist"]  instead of again using
a filter.

I think in jackson with TreeMapper you would do

data.get("relation-list").get ("artist")

whereas with the search server output you would still have to filter it,
with something like:

Collections2.filter (
     Lists.newArrayList (root.get ("relation-list")),
         new Predicate<JsonNode>() {
             @Override public boolean apply(JsonNode node) { return
node.get ("target-type") == "artist"; }
          }));

(Maybe there are easier ways to achieve this, I know very little about
using/querying json in java, or java in general).

-- kuno / warp.

_______________________________________________
MusicBrainz-devel mailing list
[hidden email]
http://lists.musicbrainz.org/mailman/listinfo/musicbrainz-devel
Reply | Threaded
Open this post in threaded view
|

Re: Adding JSON output to the webservice

Lukáš Lalinský
In reply to this post by Kuno Woudt
On Fri, Jul 6, 2012 at 6:36 PM, Kuno Woudt <[hidden email]> wrote:
> I have documented my proposed serialization using examples which should
> cover all entities and their properties:
>
> http://wiki.musicbrainz.org/User:kuno/Web_Service/JSON
>
> If you're interested in a JSON webservice, please have a look at this
> document and let me know if something seems wrong.  Come talk to me on
> irc [2] or respond here on the mailing list with your feedback.

Using the Accept HTTP header to determine the output is very impractical:

 - You can't experiment with the service in a browser, you need a
custom application. This is a huge problem, IMO.

 - If somebody sends you an URL and asks you what is wrong with the
response, you don't have the complete information to help them. It's
unlikely you will ask people to send you the complete dump of HTTP
headers.

Why not simply use a query parameter to determine the encoding?

Lukas

_______________________________________________
MusicBrainz-devel mailing list
[hidden email]
http://lists.musicbrainz.org/mailman/listinfo/musicbrainz-devel
Reply | Threaded
Open this post in threaded view
|

Re: Adding JSON output to the webservice

Paul Taylor-2
In reply to this post by Paul Taylor-2
Hi Kuno

> Just "tag" is wrong, it's not a tag, it is a list of tags.  So the key 
> should either be "tags" or "tag-list" (or something similar).

You are now saying it must be tag-list or tags because an array of tags but originally you said there wasn't any consensus about whether these values needed pluralising or not, have I missed your point ?

> 2. Removal of name-credit for artist credit
> An artist credit is already a list.

I understand what you are saying that artist-credit is really a list of artist-credit-names, but confusing in Xml because its not called artistcreditnamelist, i.e its a list of something but has a name in its own 
right (artist credit) which is the reverse. I think it would be alot clearer in Xml and Json, if artistcredit just referred to what we currently called namecredit, and artistcredit because artistcreditlist. 

In fact if you go to edit the artist in a release by clicking on the >> arrow you are presented with a dialog that contains an 'Add Artist Credit' button which allows a new name credit to be added, so in thhis dialog it appears
that artistcredit DOES refer to a component of the name rather than the whole name itself. 

So this confusion in terminology really need to be cleared up, and in my view fixed for json and Xml
 
>>>>> 3. Relationships
>>

I think you are missing the point here somewhat, my concern isn't so much side with how data is extracted using client language but the simple fact that structure has been removed from the data presented to the client. 
As there is less structure it is harder to understand and navigate. 

My other point is this isnt a json/xml thing. If you are convinced that less structure is better this change should be applied to both Json and Xml, but of course we cannot change the existing XML output like this 
which is why I'm saying these more radical changes should be applied at ws/3 whereby they can be applied to both json and xml.  

 Paul

_______________________________________________
MusicBrainz-devel mailing list
[hidden email]
http://lists.musicbrainz.org/mailman/listinfo/musicbrainz-devel
Reply | Threaded
Open this post in threaded view
|

Re: Adding JSON output to the webservice

Oliver Charles-4
In reply to this post by Lukáš Lalinský
Lukáš Lalinský <[hidden email]> writes:

> Why not simply use a query parameter to determine the encoding?

Just to let people know, we talked about this more on IRC and agreed to
allow the ?fmt query parameter and also to allow an Accept header. The
?fmt query parameter will override whatever is in Accept, in order to
allow people to do in-browser testing.

- Ollie

_______________________________________________
MusicBrainz-devel mailing list
[hidden email]
http://lists.musicbrainz.org/mailman/listinfo/musicbrainz-devel
Reply | Threaded
Open this post in threaded view
|

Re: Adding JSON output to the webservice

Kuno Woudt
In reply to this post by Paul Taylor-2
On 07/11/2012 03:22 PM, Paul Taylor wrote:
> Hi Kuno/ /
>> Just "tag" is wrong, it's not a tag, it is a list of tags.  So the
>> key should either be "tags" or "tag-list" (or something similar).
>
> You are now saying it must be tag-list or tags because an array of
> tags but originally you said there wasn't any consensus about whether
> these values needed pluralising or not, have I missed your point ?

I don't remember saying there is no consensus about pluralising.  I only
said that most style guidelines do not mention any naming convention for
collections/containers/etc..   But with that I was thinking of the
choice between e.g. "releases" or "releaseList".

I gave you two examples of style guides which recommend "releases", but
you said you'd use "releaseList" instead of "releases" for such a type
in java.

I don't care that much about "releases" vs "release-list".  I prefer
"releases", because it is prettier, but we use "release-list" in the XML
so I can see why we should use that.  The important part is that both
those names indicate a collection.  I do object to calling a list of
releases a release, because that is not what it is.


>> /  2. Removal of name-credit for artist credit
> //> A/n artist credit is already a list.
>
> In fact if you go to edit the artist in a release by clicking on the
> >> arrow you are presented with a dialog that contains an 'Add Artist
> Credit' button which allows a new name credit to be added, so in
> thhis dialog it appears that artistcredit DOES refer to a component
> of the name rather than the whole name itself.
>
> So this confusion in terminology really need to be cleared up, and in
> my view fixed for json and Xml

The documentation at http://musicbrainz.org/doc/Artist_Credit uses it
for all the names.

".. an artist credit that contains the two distinct artists ..."

So, in the documentation, the database, the perl code and the XML
schema we use artist credit to refer to the list of credited names.  It
seems the dialog needs to be fixed, not the other way around.

>>>>>> /  3. Relationships

[this was resolved on irc,
http://chatlogs.musicbrainz.org/musicbrainz-devel/2012/2012-07/2012-07-11.html#T15-19-48-417279 
]

-- kuno / warp.


_______________________________________________
MusicBrainz-devel mailing list
[hidden email]
http://lists.musicbrainz.org/mailman/listinfo/musicbrainz-devel
Reply | Threaded
Open this post in threaded view
|

Re: Adding JSON output to the webservice

Paul Taylor-2
On 11/07/2012 16:26, Kuno Woudt wrote:

> On 07/11/2012 03:22 PM, Paul Taylor wrote:
>> Hi Kuno/ /
>>> Just "tag" is wrong, it's not a tag, it is a list of tags.  So the
>>> key should either be "tags" or "tag-list" (or something similar).
>> You are now saying it must be tag-list or tags because an array of
>> tags but originally you said there wasn't any consensus about whether
>> these values needed pluralising or not, have I missed your point ?
> I don't remember saying there is no consensus about pluralising.  I only
> said that most style guidelines do not mention any naming convention for
> collections/containers/etc..   But with that I was thinking of the
> choice between e.g. "releases" or "releaseList".
>
> I gave you two examples of style guides which recommend "releases", but
> you said you'd use "releaseList" instead of "releases" for such a type
> in java.
>
> I don't care that much about "releases" vs "release-list".  I prefer
> "releases", because it is prettier, but we use "release-list" in the XML
> so I can see why we should use that.  The important part is that both
> those names indicate a collection.  I do object to calling a list of
> releases a release, because that is not what it is.
As discussed on irc Im now happy to have these pluralised, and on
balance I also prefer releases it more succint.

>
>>> /  2. Removal of name-credit for artist credit
>> //> A/n artist credit is already a list.
>>
>> In fact if you go to edit the artist in a release by clicking on the
>>>> arrow you are presented with a dialog that contains an 'Add Artist
>> Credit' button which allows a new name credit to be added, so in
>> thhis dialog it appears that artistcredit DOES refer to a component
>> of the name rather than the whole name itself.
>>
>> So this confusion in terminology really need to be cleared up, and in
>> my view fixed for json and Xml
> The documentation at http://musicbrainz.org/doc/Artist_Credit uses it
> for all the names.
>
> ".. an artist credit that contains the two distinct artists ..."
>
> So, in the documentation, the database, the perl code and the XML
> schema we use artist credit to refer to the list of credited names.  It
> seems the dialog needs to be fixed, not the other way around.
This was discussed on irc:
http://chatlogs.musicbrainz.org/musicbrainz-devel/2012/2012-07/2012-07-11.html#T15-22-41-139278

and the consensus was artistcredit refers to a list of the artist name
credits referenced in a release ectera, but there was no need to refer
to artist credit name by any name as they dont exist outside of an
artistcredit. ArtistCredit could also sometimes refer to an artist name
credit within an artist credit , and this is okay because mostly artist
credit usually only contains one artist name credit anyway. I don't
really agree with this especially if we consider Issue 1> where by it is
deemed important to name the array of releases as releases rather than
release to indicate it is an array  that can contain multiple releases,
yet it is ok to name an array of artist name credits artistcredit (in
the singular) which does not indicate that it is an array of multiple
things. But nobody else on irc agreed so I'm not going to argue against
this any more


>>>>>>> /  3. Relationships
> [this was resolved on irc,
> http://chatlogs.musicbrainz.org/musicbrainz-devel/2012/2012-07/2012-07-11.html#T15-19-48-417279
> ]
>
> -- kuno / warp.
>
>
> _______________________________________________
> MusicBrainz-devel mailing list
> [hidden email]
> http://lists.musicbrainz.org/mailman/listinfo/musicbrainz-devel
>



_______________________________________________
MusicBrainz-devel mailing list
[hidden email]
http://lists.musicbrainz.org/mailman/listinfo/musicbrainz-devel