Ideas for .json improvement

[Snack]

Feedback / Bug Report / Suggestion: Suggestion

Priority: Very Low

Description:
I've been making use of the .json for a discord bot recently, much similar to the bot that is in the SC discord. Although there are a few things I'd like to see done on the .json, a few of them are things I'd notice Arxos already mentioned in the past.


1. More explanatory variable names

- State's setup is currently looking like this:

{"s":"<type>","r":"<red team>","b":"<blue team>","a":"<matches left>","B":"bracket","T":0}

(I would use code tags, but it's kinda broken)

Which is super confusing, stats is similar, although it makes more sense:

{"p1":{"n":"<name>","p":"<pal>","a":"<author>","t":"<division>","L":<life>,"P":<meter>,"A":<attack>,"D":<defense>}}

Instead I propose changing them to be longer and more explanatory of what their use is (as it doesn't particularly hurt)

{"State":"<type>","Red":"<red team>","Blue":"<blue team>","Left":"<matches left>","Bracket(?)":"bracket","Tournament":0}

{"p1":{"Name":"<name>","Palette":"<pal>","Author":"<author>","Division (Type?)":"<division>","Life":<life>,"Power":<meter>,"Attack":<attack>,"Defense":<defense>}}

---

2. Tournament specific .json

- Currently all the tournament information is situated entirely in state.json, instead having a specific tournament.json with all the information (including the actual bracket link) would clutter each individual json less, this could be made into:

{"Session":"<type> (ex: Single Elimination 1v1 (Maybe include rating/division if not Type?))","Type":"<type> (ex: 2nd Division)","ID":0 (ex: 23283),"Bracket":"<link> (ex: https://spriteclub.challonge.com/tournament_23283)"}

This would ultimately transform into:

{"Session":"Single Elimination 1v1","Type":"2nd Division","ID":23283,"Bracket":"https://spriteclub.challonge.com/tournament_23283"}

The image of the tournament could then be gotten by just adding .svg to the bracket url as such:
https://spriteclub.challonge.com/tournament_23283.svg

This would, obviously, eliminate the tournament bits of state.json so it would only look like this:

{"State":"<type>","Red":"<red team>","Blue":"<blue team>","Left":"<matches left>"}

---

3. Exhibition specific .json

- In the discord where my own .json reading bot is located, I ping people when their favorite characters appear in matches, however it would also be nice to ping when certain exhibitions appear. Sometimes I might be busy, but would like to know when a friend's exhibition appears in exhibition, I could ask them to ping me when, or check whenever the sound effect of a new match starts, but I'd prefer it to be simpler. The Exhibition json would contain no more information than what you would get from the individual's exhibition if you were to check the queue anyway. Therefore:

{"Creator":"<name> (ex: Snack)","Date":"<Date Created> (ex: 04/09)","Message":"<comment> (ex: Random 4th Division 12p)","Stage":"<Custom Stage, if applicable> (ex: Burning Osaka CVS2)","Music":"<Custom Music, if applicable> (ex: Dokken - Into The Fire)"}

The last two are obviously not as important or useful as the first three, but it wouldn't hurt to add if all the information comes from the same place. Ultimately as an example here's what it would look like complete:

{"Creator":"Snack","Date":"04/09","Message":"Random 4th Division 12p","Stage":"Burning Osaka CVS2","Music":"Dokken - Into The Fire"}

---

These are but a few ideas I had for improving the .json (for now), going forward I may have more ideas, but these are mostly basic changes for now.
Thanks!

[datner]

i'd very heartily advise against using capital letters in JSON for the off chance someone mistakes an l and an I, or forgets to capitalize a letter, making for annoying bugs.

{
  "state": "<type>",
  "red": "<red team>",
  "blue": "<blue team>",
  "left": "<matches left>",
  "bracket(?)": "bracket",
  "tournament": 0
}

I have no idea what kind of DB and data manipulation is being done, nor the full context for this.
So I truly might be talking out my ass.. But if I were to design this API I'd go for a more logic-driven structure which is a best practice for outward-facing API 
Instead of a direct access API which is common for internal work. so I'd opt to something like this

{
  "state": string,
  "teams: {
    "red": {
      "name(?)": string,
      "fighters": Fighter[] // maybe some more metadata about the fighters? idk, can just be string array with their name
     },
    "blue": { ... }
  }, // or even teams: [{"side": "red", "foo": "bar"}, {...}] if more than 2 teams is something possible in theory
  "matches": {
    "current": number,
    "amount": number,
    "history": MatchMetadata[] // for sharing time, hp left, winning team, win condition or idk
  },
  "bracket(?)": number, // I think they are number? I don't remember
  "tournament": TournementMetadata || null
}

The tournament might be a logical entity that exists only while actual tourneys are happening, but it's also possible that internally everything is technically a tourny so idk about that last entry in the JSON schema.

anyways, this JSON structure is much more extendable and robust. Allowing for future additions without breaking previous implementations that relied on the API.
for example. if you decide to add a fighter "nickname" with a name that the crowd gave the char or something silly, you can just add a key to the Fighter entity, and all existing solutions will never know the difference. (Unless they are iterating over the keys of the Fighter entity non-generically, but that's a bad practice in and of itself).

Again, I am completely unfamiliar with the internal structure here but that is my 2 cents

[Snack]

i'd very heartily advise against using capital letters in JSON for the off chance someone mistakes an l and an I, or forgets to capitalize a letter, making for annoying bugs.

{
  "state": "<type>",
  "red": "<red team>",
  "blue": "<blue team>",
  "left": "<matches left>",
  "bracket(?)": "bracket",
  "tournament": 0
}

I have no idea what kind of DB and data manipulation is being done, nor the full context for this.
So I truly might be talking out my ass.. But if I were to design this API I'd go for a more logic-driven structure which is a best practice for outward-facing API 
Instead of a direct access API which is common for internal work. so I'd opt to something like this

{
  "state": string,
  "teams: {
    "red": {
      "name(?)": string,
      "fighters": Fighter[] // maybe some more metadata about the fighters? idk, can just be string array with their name
     },
    "blue": { ... }
  }, // or even teams: [{"side": "red", "foo": "bar"}, {...}] if more than 2 teams is something possible in theory
  "matches": {
    "current": number,
    "amount": number,
    "history": MatchMetadata[] // for sharing time, hp left, winning team, win condition or idk
  },
  "bracket(?)": number, // I think they are number? I don't remember
  "tournament": TournementMetadata || null
}

The tournament might be a logical entity that exists only while actual tourneys are happening, but it's also possible that internally everything is technically a tourny so idk about that last entry in the JSON schema.

anyways, this JSON structure is much more extendable and robust. Allowing for future additions without breaking previous implementations that relied on the API.
for example. if you decide to add a fighter "nickname" with a name that the crowd gave the char or something silly, you can just add a key to the Fighter entity, and all existing solutions will never know the difference. (Unless they are iterating over the keys of the Fighter entity non-generically, but that's a bad practice in and of itself).

Again, I am completely unfamiliar with the internal structure here but that is my 2 cents

I agree with your comment, primarily the reason I didn't "over-extend" it per se (aka adding some of the information you've added) is for similar reason as you, merely because I've no idea exactly what information is even being handled between db to frontend. Combining state.json and stats.json might be the better method in the long run. Another reason I didn't really add data was because Arxos has previously mentioned he'd prefer to add as little information that would support bot behaviour.

Ultimately I think your idea with lower caps is better, as for the improved overall combined json it is necessary to hear what Arxos thinks about it. It might compliment bot behaviour too much and he'd opt against adding that much information. 

- As for the tourney, currently the tourney already exists only while tourneys actually happen. As an example let me show you what the difference is:

{"s":"m","r":"Gikoneko","b":"Chinko","a":"94 matches left until next tournament","B":"bracket","T":0}

Notice T:0, that means a tournament is currently not running, I'm not entirely sure what the "B":"bracket" is meant to be used for, I don't believe I've ever seen it change from bracket. However, during an actual tournament the only way to really see a tournament is under progress is that T is not 0, or look for keywords (aka left until exhibitions I believe it would say if during tournament, or maybe tournament matches left I don't remember off the top of my head) in "a"

EDIT: Off-topic curiousity, is it just me or are the code brackets slightly broken on this forum? They seem to not really have gotten the memo about dark mode and are excruciatingly bright.

[Snack]

With the new changes adding !nexttournament and !custom, adding these into the json would be very nice as well, if possible. I would love to be able to check the json for the next custom mode!

[Arxos]

I'll look into improving the jsons somewhere in the next 2 weeks, as well as including the exhibs/tourney/custom mode. And yeah about the naming thing, the json standard that I'm used to nowadays (and that I generally see everywhere) is to do lowercase with underscores. So along the lines of "bracket_url".

EDIT: Also, regarding the "B" field. Initially this gave the URL that would be used for the bracket button. The problem is that this information wasn't being sent for things outside of the main page, so I eventually just changed the bracket link to always go to spriteclub.tv/bracket. This currently then redirects you to the challonge page, although I need to change this to the embed again since I noticed that they're properly supporting embeds again a while ago. Either way, this field is outdated and should be removed.

[Snack]

Just talked to Erxos about the json again and I thought I may as well update the thread with a few more findings that could prove useful for an api update.

---

1.
General json cleanup and property naming improvement.

Some of the property names are confusing at first glance, giving them names that make them more on par with what data they display makes it easier to use and more welcoming to people who want to make something using it. Providing the actual json files aren't changed, state, stats, exhibition-list and bets could all use a slight change name change, it was already discussed in the thread however, so I won't be going into depth with it.

---

2.
Additions to current json files

State.json should also display the current gamemode, along with the next custom (if the current gamemode is not custom), next tournament etc.

Stats.json seems fine as is, although it'd be nice if it showed the character's database/character ID, and during debuts when a NEW character shows up, it'd also be nice to see the character's current matches, 0 (or 1) for a character's first debut match.

Bets.json is fine as is.

Exhibition-list should also show the current exhibition, so instead of just only showing the queue, there should be a queue subschema showing the whole queue, and a current subschema that shows the current exhibition with the same information as the queue does currently.

---

3.
Character API query

Depending on the upcoming update to the character db, being able to query a specific character ID and getting some (not all) of the data would be nice, such as name,author,palettes,tags(if applicable at the time),health,def,meter,attack etc.

---

That's about what I've got so far all summed up in one message.