1 hour ago, Ardaedhel said:

What do you guys think about a JSON standard that looks like this?

This is modeled heavily on the X-Wing Squad schema, with some changes made to accommodate our considerations. Currently, this mostly impacts the fleet builders, so that's @fab74 , @Green Knight , @Nevetz , Ryan Kingston, and David Martinez (AFD).

That looks good, and I don't know what these peoples' backends look like but I'd like to throw out a slight modification under the assumption list builders will produce this from an export option or whatever.

Changes made:

• Added "mode" to indicate if tournament, casual, campaign, or whatever
• Made "objectives" into object with indication of color of objective
• Added "cost" and "text" keys to ships/squadron objects because why not, the more info the better
• Made upgrades into an array of objects because upgrades can have multiple attributes (i.e. modification, boarding parties)
• The "type" is an array of strings that describe the slot or any other list building restrictions attached to an upgrade object
• Additionally, since upgrades are objects, if in the future if more details are needed about a specific upgrade then they can be added (i.e. exhaustible)
• Removed the "-swm27" from Leia. I feel like you would want to know when there are duplicates in the list so that the GUI or whatever can flag it, though this shouldn't really be an issue since most list builders handle duplicates fine already so the "-swm27" seems unnecessary
• Made list of squadrons into array of objects, each squadron has a "name" and "type"
• The "name" is so that for upgrades like Darth Vader the boarding party, admiral, and squadron all have the same key (the name)
• The "type" is simply the type of squadron, though more attributes can be added to this in the future if necessary
• Generics are differentiated through having an empty "name" field

{
  "name": "Armada Fleet Format v0.1 - Example Fleet",
  "faction": "rebel",
  "points": 400,
  "mode": "tournament",
  "version": "0.1.0",
  "description": "An example fleet list.  If you come with this thing, you're braver than I thought.",
  "objectives": {
    "assault": "targetingbeacons",
    "defense": "fleetambush",
    "navigation": "navigationhazards"
  },
  "ships": [
    {
      "name": "cr90corvetteb",
      "cost": 39,
      "upgrades": [
        {
          "name": "leiaorgana",
          "type": ["commander"],
          "cost": 38,
          "text": "..."
        },
        {
          "name": "highcapacityionturbines",
          "type": ["ioncannons", "modification"],
          "cost": 7,
          "text": "..."
        }
      ]
    },
    {
      "name": "assaultfrigatemarkiia",
      "cost": 39,
      "upgrades": [
        {
          "name": "boardingtroops",
          "type": ["offensiveretrofit", "weaponsteam"],
          "cost": 3,
          "text": "..."
        }
      ]
    }
  ],
  "squadrons": [
    {
      "name": "lukeskywalker",
      "type": ["xwingsquadron"],
      "cost": 20,
      "text": "..." 
    },
    {
      "name": "",
      "type": ["z95squadron"],
      "cost": 7,
      "text": ""
    },
    {
      "name": "",
      "type": ["z95squadron"],
      "cost": 7,
      "text": ""
    }
  ],
  "vendor": {
    "armadafleetdesigner": {}
  }
}

In principle, I'm okay with this. I will need to add a few fields to my back-end to be able to allow KDY to support this (a unique field in the table).

I'm not sure text is necessary on the upgrades. Same goes for cost on ships. I feel like if this standard is designed to be a cross-platform communication protocol, then stats aren't necessary. For example, if someone were to import this into KDY, I would just use the names as a cross-reference to content that exists on my back end. for example "assaultfrigatemarkiia" in this standard is cross-referenced in my system as content_id "25xYkava" which I can then use to describe everything such as Point Cost, and so on.

46 minutes ago, GalacticFister said:

That looks good, and I don't know what these peoples' backends look like but I'd like to throw out a slight modification under the assumption list builders will produce this from an export option or whatever.

Changes made:

• Added "mode" to indicate if tournament, casual, campaign, or whatever
• Made "objectives" into object with indication of color of objective
• Added "cost" and "text" keys to ships/squadron objects because why not, the more info the better
• Made upgrades into an array of objects because upgrades can have multiple attributes (i.e. modification, boarding parties)
• The "type" is an array of strings that describe the slot or any other list building restrictions attached to an upgrade object
• Additionally, since upgrades are objects, if in the future if more details are needed about a specific upgrade then they can be added (i.e. exhaustible)
• Removed the "-swm27" from Leia. I feel like you would want to know when there are duplicates in the list so that the GUI or whatever can flag it, though this shouldn't really be an issue since most list builders handle duplicates fine already so the "-swm27" seems unnecessary
• Made list of squadrons into array of objects, each squadron has a "name" and "type"
• The "name" is so that for upgrades like Darth Vader the boarding party, admiral, and squadron all have the same key (the name)
• The "type" is simply the type of squadron, though more attributes can be added to this in the future if necessary
• Generics are differentiated through having an empty "name" field

Thanks for the input.

Keep in mind that "vendor" is there as an extensibility feature so that anybody can carry specific data like "list author" or "event type" or something for your specific implementation, if you want.

• Added "mode" to indicate if tournament, casual, campaign, or whatever
  • I can get on board with this as a non-mandatory field
• Made "objectives" into object with indication of color of objective
  • Disagree. Extraneous: doesn't add any new information--if you want to track color, you can do that in your backend.
• Added "cost" and "text" keys to ships/squadron objects because why not, the more info the better
  • Disagree. Extraneous: doesn't add any new information. Again, this can all be tracked in your backend for an overall storage and processing savings.
• Made upgrades into an array of objects because upgrades can have multiple attributes (i.e. modification, boarding parties)... Additionally, since upgrades are objects, if in the future if more details are needed about a specific upgrade then they can be added (i.e. exhaustible)
  • I like this model better, specifically for tracking dual-slot upgrades. Most of the additional data tracking should be done on your side, though.
• The "type" is an array of strings that describe the slot or any other list building restrictions attached to an upgrade object
  • I can dig it.
• Removed the "-swm27" from Leia. I feel like you would want to know when there are duplicates in the list so that the GUI or whatever can flag it, though this shouldn't really be an issue since most list builders handle duplicates fine already so the "-swm27" seems unnecessary... Made list of squadrons into array of objects, each squadron has a "name" and "type"... The "name" is so that for upgrades like Darth Vader the boarding party, admiral, and squadron all have the same key (the name)... The "type" is simply the type of squadron, though more attributes can be added to this in the future if necessary... Generics are differentiated through having an empty "name" field
  • Okay, I was initially not on board with this in the interest of simplicity, but after thinking it through that makes sense: allows for quick checking for uniques and still the capability to differentiate between identically-named uniques.

17 minutes ago, Ardaedhel said:

Made upgrades into an array of objects because upgrades can have multiple attributes (i.e. modification, boarding parties)... Additionally, since upgrades are objects, if in the future if more details are needed about a specific upgrade then they can be added (i.e. exhaustible)

• I like this model better, specifically for tracking dual-slot upgrades. Most of the additional data tracking should be done on your side, though.

Actually, we could just drop everything but the name of the upgrade, and everything else could be tracked on the backend. I think the minimum you'd need here would look like:

    {
      "name": "raideriiclasscorvette",
      "upgrades": [
        "darthvader-swm29",
        "admiralmonteferrat"
      ]
    }

I guess the question is, is that easier to work with than:

    {
      "name": "raideriiclasscorvette",
      "upgrades": [
        { 
          "name": "darthvader",
          "type": ["offensiveretrofit", "weaponsteam"]
        },
        { 
          "name": "admiralmonteferrat",
          "type": ["officer"]
        }
      ]
    }

The former requires you to pull the "unique" portion of the name out of your backend to do the uniqueness comparison--but then, you're already doing that query anyway. Cause you're not doing operations directly off of the ingested list's data... right?

1 minute ago, Ardaedhel said:

Actually, we could just drop everything but the name of the upgrade, and everything else could be tracked on the backend. I think the minimum you'd need here would look like:

I guess the question is, is that easier to work with than:

The former requires you to pull the "unique" portion of the name out of your backend to do the uniqueness comparison--but then, you're already doing that query anyway. Cause you're not doing operations directly off of the ingested list's data... right?

The more I think about it, since mostly everyone who has a stake in this already has a mature backend (or so it seems) it's probably worth just doing the absolute minimum, so probably the first one I guess.

36 minutes ago, Ardaedhel said:

Actually, we could just drop everything but the name of the upgrade, and everything else could be tracked on the backend. I think the minimum you'd need here would look like:

    {
      "name": "raideriiclasscorvette",
      "upgrades": [
        "darthvader-swm29",
        "admiralmonteferrat"
      ]
    }

I guess the question is, is that easier to work with than:

    {
      "name": "raideriiclasscorvette",
      "upgrades": [
        { 
          "name": "darthvader",
          "type": ["offensiveretrofit", "weaponsteam"]
        },
        { 
          "name": "admiralmonteferrat",
          "type": ["officer"]
        }
      ]
    }

The former requires you to pull the "unique" portion of the name out of your backend to do the uniqueness comparison--but then, you're already doing that query anyway. Cause you're not doing operations directly off of the ingested list's data... right?

It was originally my intent to format the fleet builder on KDY to do the simpler format here for exactly the reason you mention here.

I think the "type" field in the upgrade is also extraneous for the same reasons as "text" and "cost" was.

Yeah, my vote is for the condensed layout of the above.

It seems ok to me, but I'd need to read it in detail. I've already seen that you are dealing with dual upgrade cards, which is good. I guess the only change I have to make to my backend is a new column for each card that links them to the "standardized" name on the JSON.

This also means that builders could publish a restful JSON API, allowing custom programs (like a campaign tracker) to interact with it.

What? A guy can dream, can't he?

1 hour ago, Democratus said:

This also means that builders could publish a restful JSON API, allowing custom programs (like a campaign tracker) to interact with it.

What? A guy can dream, can't he?

What... you mean a *standard*? Let's get ISO in here...

1 hour ago, Democratus said:

This also means that builders could publish a restful JSON API, allowing custom programs (like a campaign tracker) to interact with it.

What? A guy can dream, can't he?

If people accept the final version of this JSON as the standard model for a fleet, I don't see any problem adding an import/export function to any program, not just builders.

We (speaking of builder owners) should have everything already set to try an export with an agreed model.

23 minutes ago, Nevetz said:

If people accept the final version of this JSON as the standard model for a fleet, I don't see any problem adding an import/export function to any program, not just builders.

We (speaking of builder owners) should have everything already set to try an export with an agreed model.

The X-wing builders, some of them anyway, can already export/import like this. For example fab's.

I wish I had the time to contribute to something like this because I do enterprise web services for a living, but I don't get enough free time as it is. So I'll just contribute one suggestion and say thanks to everyone who is willing to contribute their time and skill into these projects. My suggestion comes from my work background of a worldwide user base, which is also what Armada has.

My suggestion is to have internationalization support as part of your standard so that our wonderful international community can have local text for all the cards in all languages Armada is released in. (Maybe card titles and required equip rules for sure, card text optional?). In other words, separate the model data from the view data, so that views can have language specific data if the app developer is willing to implement locale switching. Maybe the data could be on GitHub or something where it's available to any app that wants it, and can be community tracked and maintained? This standard data would also include all the localized text so that if the app developers wish to implement that feature for their users, they have the data to do so.

For anybody not following that, here's more detail: There's a difference between "the standard" which allows you to have a common structure/schema, and "the standard" of all the data (i.e. cards, etc.) in the game formatted for the schema standard.

Also, If I were in charge, I'd require a unique id for every single card as part of the standard schema - this enforces uniqueness of every single card while still allowing the data to be compared however is appropriate for the view. That unique id could be either a UUID or a compound value of "name + type" (whatever combination guarantees uniqueness). Internationalization is easier to deal with if you have unique ids for everything IMHO (separation from what we think of as the "name" of the thing, since people often think in their mind that the "name" is the id, when it really isn't - Leia and Vader are two cases of this). If "view" type stuff is separated out then you can look it up without passing it around (i.e. apps can pass the minimal data to each other which you all are already talking about, and this localized stuff won't impact any of that if you provide a way for it to be looked up in the UI).

1 minute ago, Ken-Obi said:

I wish I had the time to contribute to something like this because I do enterprise web services for a living, but I don't get enough free time as it is. So I'll just contribute one suggestion and say thanks to everyone who is willing to contribute their time and skill into these projects. My suggestion comes from my work background of a worldwide user base, which is also what Armada has.

My suggestion is to have internationalization support as part of your standard so that our wonderful international community can have local text for all the cards in all languages Armada is released in. (Maybe card titles and required equip rules for sure, card text optional?). In other words, separate the model data from the view data, so that views can have language specific data if the app developer is willing to implement locale switching. Maybe the data could be on GitHub or something where it's available to any app that wants it, and can be community tracked and maintained? This standard data would also include all the localized text so that if the app developers wish to implement that feature for their users, they have the data to do so.

For anybody not following that, here's more detail: There's a difference between "the standard" which allows you to have a common structure/schema, and "the standard" of all the data (i.e. cards, etc.) in the game formatted for the schema standard.

Also, If I were in charge, I'd require a unique id for every single card as part of the standard schema - this enforces uniqueness of every single card while still allowing the data to be compared however is appropriate for the view. That unique id could be either a UUID or a compound value of "name + type" (whatever combination guarantees uniqueness). Internationalization is easier to deal with if you have unique ids for everything IMHO (separation from what we think of as the "name" of the thing, since people often think in their mind that the "name" is the id, when it really isn't - Leia and Vader are two cases of this). If "view" type stuff is separated out then you can look it up without passing it around (i.e. apps can pass the minimal data to each other which you all are already talking about, and this localized stuff won't impact any of that if you provide a way for it to be looked up in the UI).

For KDY, i use a 8-character base62 string for my primary key, so there's that.

I also agree that internationalization would be nice. realistically speaking, I cannot support i18n on KDY itself (there's already a lot going on and the burden on the rendering engine would get ridiculous - maybe for version 3?). Let me mull it over and see if I really want to add that to my already extensive DB Schema.

19 minutes ago, Ken-Obi said:

Also, If I were in charge, I'd require a unique id for every single card as part of the standard schema - this enforces uniqueness of every single card while still allowing the data to be compared however is appropriate for the view. That unique id could be either a UUID or a compound value of "name + type" (whatever combination guarantees uniqueness). Internationalization is easier to deal with if you have unique ids for everything IMHO (separation from what we think of as the "name" of the thing, since people often think in their mind that the "name" is the id, when it really isn't - Leia and Vader are two cases of this). If "view" type stuff is separated out then you can look it up without passing it around (i.e. apps can pass the minimal data to each other which you all are already talking about, and this localized stuff won't impact any of that if you provide a way for it to be looked up in the UI).

This is the intent of the "name"+"-"+"SKU" thing here, which is the model X-wing's standard uses to globally distinguish duplicate names:

18 hours ago, Ardaedhel said:

"darthvader-swm29"

Does that scratch this itch? That model currently makes every name globally unique; and I'm not sure I see FFG releasing multiple Lando Calrissians in the same expansion pack in the future.

6 minutes ago, Ardaedhel said:

This is the intent of the "name"+"-"+"SKU" thing here, which is the model X-wing's standard uses to globally distinguish duplicate names:

Does that scratch this itch? That model currently makes every name globally unique; and I'm not sure I see FFG releasing multiple Lando Calrissians in the same expansion pack in the future.

I think it's more developer friendly to have the id be readable (so I personally wouldn't use a UUID or sequence unless there was a super compelling reason to, for this use case), so I do like your suggested strategy. If/When FFG releases the same named card in the same expansion then the rule would break, but in that case, you could always just append the card type to the name + SKU. However since there aren't many card names that overlap, I think the suggestion of name + card type is also good. I really don't like "name" by itself as an id (primary key) but a compound key is great IMHO.

2 minutes ago, Ken-Obi said:

I think it's more developer friendly to have the id be readable (so I personally wouldn't use a UUID or sequence unless there was a super compelling reason to, for this use case), so I do like your suggested strategy. If/When FFG releases the same named card in the same expansion then the rule would break, but in that case, you could always just append the card type to the name + SKU. However since there aren't many card names that overlap, I think the suggestion of name + card type is also good. I really don't like "name" by itself as an id (primary key) but a compound key is great IMHO.

So you think it should be generalized to apply to all components? I'd only been using it for cards that have duplicate names; but applying the requirement to everything future-proofs the schema. I could get on board with that.

30 minutes ago, FoaS said:

For KDY, i use a 8-character base62 string for my primary key, so there's that.

I also agree that internationalization would be nice. realistically speaking, I cannot support i18n on KDY itself (there's already a lot going on and the burden on the rendering engine would get ridiculous - maybe for version 3?). Let me mull it over and see if I really want to add that to my already extensive DB Schema.

Just for brainstorming purposes, if there was a central repository that was considered "authoritative" (probably community developed and curated), then the JSON schema could be published (and versioned) for every app to use, a separate "file" or something could contain all the cards, and also separate localization "files" (but definitely english since that's probably the largest user base) could support the localized text of each card.

If that were the case, then each app could have their own "business rules" for how they want to use the data.

-Cool builder apps could allow for list building with enforced restrictions on cards. In fact there could be data in the common repo for how to enforce list building within the rules constraints and each app could present this however they want.

-Cool viewer apps (like KDY, or view components in apps like Armada Warlords) could pick a default language and retrieve just that translated data, but then choose whether or not to allow for language switching if they wanted to - then they'd just retrieve the other translated data (from the common repo).

Etc.

I almost hesitated to contribute because I sympathize with all the existing app developers out there - everything discussed so far from the start of the thread is likely going to be a lot of work for developers to switch to, and I just added a little more work on top of that for everybody. However, I think if the only thing that happens is you all plan for internationalization from the start, that gives everyone the option to actually implement it either now or later.

27 minutes ago, Ardaedhel said:

So you think it should be generalized to apply to all components? I'd only been using it for cards that have duplicate names; but applying the requirement to everything future-proofs the schema. I could get on board with that.

I personally would, so that every card is easily lookupable, which helps in a variety of different ways. Translated text is one example. Another is that if it made sense, apps could share lists with each other by simply including the card ids and their relationship which gives you a minimal set of data going across the wire (I'm never really concerned with file size of this stuff because it's small and storage is cheap, but bandwidth is a different story for some people). So for those that don't follow, what I mean is that if you require a unique id as a property of every single card, then an app can communicate a list to another app that looks something like:

["ISD-Kuat_ship":["Vader_commander", "Intel-Officer_officer", "Avenger_shipTitle"]]

(Of course you can use the expansion name instead of the card type, I just picked card type for this example so I could be lazy and not have to look up the actual expansion.)

As those are simply ids and their relationship (a ship to a list of upgrade cards), then if you're communicating that data to a builder app then the builder app could look up those card ids and apply the list constraints to see if it is valid. If it's a card viewer app, then it simply uses those ids + the selected (or default) locale and looks up the translated data.

Of course you can also have separate schema that defines a valid list, or a valid tournament result, etc - as you all have already discussed above. If everything has an id and it's in a schema that makes sense to communicate with, then that schema doesn't necessarily have to send anything across the wire (or save in a file) other than the id.

Just a thought.

On 07/03/2018 at 9:39 PM, Ardaedhel said:

What do you guys think about a JSON standard that looks like this?

{
  "name": "Armada Fleet Format v0.1 - Example Fleet",
  "faction": "rebel", 
  "points": 400,
  "version": "0.1.0",
  "description": "An example fleet list.  If you come with this thing, you're braver than I thought.",
  "objectives": ["targetingbeacons", "fleetambush", "navigationhazards"],
  "ships": [
    {
      "ship": "cr90corvetteb",
      "upgrades": {
        "commander": [
          "leiaorgana-swm27"
        ], 
        "officer": [
          "intelofficer"
        ],
        "supportteam": [
          "enginetechs"
        ],
        "defensiveretrofit": [
          "clusterbombs"
        ],
        "ioncannons": [
          "nk7ioncannons"
        ],
        "title": [
          "jainaslight"
        ]
      }
    }, 
    {
      "ship": "modifiedpeltaclassassaultship",
      "upgrades": {
        "officer": [
          "landocalrissian",
          "skilledfirstofficer"
        ],
        "supportteam": [
          "firecontrolteam"
        ],
        "fleetcommand": [
          "allfightersfollowme"
        ],
        "ordnance": [
          "expandedlaunchers"
        ],
        "title": [
          "phoenixhome"
        ]
      }
    }
  ], 
  "squadrons": [
    "lukeskywalkerxwingsquadron",
    "wedgeantillesxwingsquadron",
    "z95headhuntersquadron"
  ],
  "vendor": {
    "armadafleetdesigner": {}
  }
}

This is modeled heavily on the X-Wing Squad schema, with some changes made to accommodate our considerations. Currently, this mostly impacts the fleet builders, so that's @fab74 , @Green Knight , @Nevetz , Ryan Kingston, and David Martinez (AFD).

Hello,

I am ok with this approach, it has to match the x-wing one the closest than possible. If you can go with a github like for x-wing it will be great and easier for everybody to implement it in any tools.

Thank you for the effort.

5 minutes ago, fab74 said:

Hello,

I am ok with this approach, it has to match the x-wing one the closest than possible. If you can go with a github like for x-wing it will be great and easier for everybody to implement it in any tools.

Thank you for the effort.

Yup, I'm working on getting it written up. I'm modeling it as closely as practical on @WickedGrey 's X-wing standard to make it as easy as possible to incorporate for people like you and whoever's maintaining Cryodex.

Alternative to the -swm25 thing is just "darthvader_2" with the number incremented each release. I know it's less ideal, but it lends itself to be uniform. I have no strong opinion one way or another, so long as consistency happens.

My own proposal for the standard. A small modification to those that exist already, but all items that are in arrays are instead objects in stead of just string values.

{
	"title":"My Fleet",
	"objectives":[
		{
			"name":"blockaderun"
		},
		{
			"name":"capturethevip"
		},
		{
			"name":"minefields"
		}
		
	],
	"ships":[
		{
			"name":"assaultfrigatemk2a",
			"upgrades":[
				{"name":"leiaorgana_2"},
				{"name":"clusterbombs"}
			]
		},
		{
			"name":"cr90corvetteb",
			"upgrades":[
				{
					"name":"adartallon"
				}
			]
		}
	],
	"squadrons": [
		{
			"name":"wedgeantilles_xwingsquadron"
		},
		{
			"name":"xwingsquadron", 
			"count":2
		},
		{
			"name":"bwingsquadron",
			"count":1"
		}
	],
	"metadata":{
	
	}
}

Another idea related to this is to allow for vendor-specific fields by doing a xyz_ prefix to the key. For example, let's say I want to embed KDY's id to that assault frigate in my example.

{
			"name":"assaultfrigatemk2a",
			"upgrades":[
				{"name":"leiaorgana_2"},
				{"name":"clusterbombs"}
			],
			"kdy_itemid":"12Afef"
		}

Obviously the addition to the standard benefits me greatly, but hey - I figure if I say it, it may get adopted

I like vendor specific ids that can point to these "standard" ids, but I'd do more of a generic map approach which puts all vendor specific stuff in the same place (I think it's more clear that way):

"vendorProperties": {"kdy_itemid":"12Afef", "FabItemId":"thisIsJustAnExample", "FabProductImageLink":" https://images-cdn.fantasyflightgames.com/filer_public/84/07/840768b4-ccd2-4431-9cd6-cca952d46e36/swm03_main.png "}

Etc...

Doing it like this gives each vendor a kind of "junk drawer" for any attribute they find useful, and anything that doesn't use any vendor attributes can skip processing all those attributes by just doing nothing when they process "vendorProperties".

I fully admit I have no skin in the game here, just giving advice based on my experience doing this sort of thing, so please feel free to disregard whatever you want.

if vendorProperties can exist on the item-level instead of on the list-level, I'm cool with that.

@Ken-Obi

For my own edification, when it comes to internationalization, do you tend to support separation of languages by LCID code (en-us, fr-lu) or by simple language code (en, fr)?

If the translation is done in house, then I support whatever they're willing to do (which is usually just the simple code). My last big project had the data translated into 40ish languages, so this is kind of a fun problem to solve because it often surprises users who aren't accustomed to such good customer service.

In this case, if FFG releases English text for the UK that is different from the US (and I have no idea if they do or not), then I'd switch to the locale specific string when storing stuff. I also would have a list of officially supported languages for UI components to have an easy drop down list source (or if all this stuff is really in a db, then provide an API that queries for "officially supported languages"). In the name of keeping it simple to get this standard off the ground, then I'd just poke around and see if the UK text is different from the US text and if not, just use the simple lang codes.

Designing an API with a web service implementation and data persistence is one of the fun things I like about my job... My suggestions in this thread are a little bit overkill for just getting something done and working, but I think some relatively simple "overkill" additions now will make your lives far easier down the road. IMHO