Ideas for .json improvement
#1
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:
Quote:{"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:
Quote:{"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)

Quote:{"State":"<type>","Red":"<red team>","Blue":"<blue team>","Left":"<matches left>","Bracket(?)":"bracket","Tournament":0}
Quote:{"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:

Quote:{"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:
Quote:{"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:
Quote:{"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:

Quote:{"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:

Quote:{"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!
Reply
#2
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.


Quote:{
  "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

Quote:{
  "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
Reply
#3
(05-09-2020, 11:13 PM)datner Wrote: 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.


Quote:{
  "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

Quote:{
  "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:
Quote:{"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.
Reply