Api: Component Schema URLs for Array types

[lowlines]

I noticed that the urls for Array type components (ie https://bungie-net.github.io/multi/schema_BungieMembershipType[].html#schema_BungieMembershipType[]) have "[]" in the url. While it appears to be valid, its probably not good practice to have brackets in the url. The regular expression for generating the filepaths should be replace(/[\<\>\.,\[\]]/, "-")

[vthornheart-bng]

Ah, good call! I missed that.

I'm also considering, when I fix those other bugs in the markup, to make the Schemas for Dictionaries and Lists be inline instead of as their own entities. I've got to think about it more, but I think I've made it more confusing than I'd like by having those List/Dictionary entities be separate, even if it's a bit redundant to have them defined individually within the schemas that use them.

Let me know what you think. I'm 50/50 on it right now.

[lowlines]

I'm still just trying to get the example code to render correctly. It I think it'd be easier to make those observations when you can actually see the structure laid out in front of you. Definitely funky having <>[], in the names though. Due to the way the Github Wiki manages the Markdown files (and my own desire for self inflicted pain and misery), I had to write a search script to match up the generated files with their corresponding components so I could feed the names back into it for the html doc generation. It's definitely great to have the data structures split out into reusable components though!

[vthornheart-bng]

Ah, good deal - in that case then, perhaps I'll just try to give them a more gentle naming convention. Though that might mean it'd end up being something like "DictionaryOfUint32AndDestinyProgression" ... eh, I don't like that either. Hmm. I'm open to suggestions.

[lowlines]

Discovered a naming conflict between SchemaComponents and ResponseComponents with the exact same name/id (ie User.GeneralUser). This is only an issue in environments where having 2 things with the same filename (despite living in totally different locations, ie Github Wikis) causes issues. Working on a fix for it for my generator by appending "Response" to any responses that conflict, will look the same on the surface, but with have completely different urls.

[lowlines]

Was looking at trying to truncate the display text for references so like "DictionaryComponentResponse" becomes "DictionaryComponentResponse" but there's some funky stuff going with my code.

"Destiny.HistoricalStats.DestinyLeaderboardResults" outputs as "Dictionary>" (which I think is because "Destiny.HistoricalStats.DestinyLeaderboard" is missing as mentioned in that other issue).

(a few hours later and after some sleep)

I've decided to abandon shortening labels for now since I'm breaking more stuff than I am fixing it. I reckon the components could do with a summary field or something which has a shorter display name if messing with the urls/paths breaks the spec. I don't know how code generators deal with it but stuff like "Destiny.Definitions.Common.DestinyDisplayPropertiesDefinition" displays horribly in a table on a docs page since it has to fit on one line.

[vthornheart-bng]

Hmm, yes - technically according to the Swagger standard, Responses and Schemas don't necessarily have to have universally unique identifiers, only within their own respective categories. However, while I'm doing work on the generator tomorrow, I'll see if I can find a better pattern.

Yeah, the long path names are really in case of name collisions: it roughly reflects our own namespaces in our code (though I truncated some of it... our namespaces really got out of hand, to be honest). I don't know for certain if we have any name collisions, and I haven't really bothered to check: but I figured it was better to be safe than sorry.

[lowlines]

For responses I decided to drop generating them out as separate pages since they are basically covered in the Response Example on their respective Endpoint page.

Been working through the schema components and trying to understand the meaning behind the URLs. In discussions with the DTR guys, I understand there's a lot of C# referencing here? As someone who doesn't program in C#, there is a lot of foreign syntax that isn't all that meaningful so perhaps the URLs should be made more language generic?

I like the way Definitions are named as they read clearly where they sit in the hierarchy and lack any special characters in the name. I could also take something like "Destiny.Definitions.DestinyProgressionDisplayPropertiesDefinition" and turn it into a shorter page title with a breadcrumb/subtitle. ie

DestinyProgressionDisplayPropertiesDefinition

Destiny / Definitions

So looking at other patterns here's what I'd do to make them more generic.

• BungieMembershipType[]
  ** BungieMembershipTypeArray
• SingleComponentResponse
  ** Destiny.Entities.Profiles.DestinyVendorReceiptsSingleComponentResponse
• DictionaryComponentResponse
  ** Destiny.Entities.Characters.DestinyCharacterDictionaryComponentResponse
• DestinyItemComponentSet
  ** (not sure how to read this one)
• Destiny.Definitions.DestinyVendorCategoryEntryDefinition+DestinyVendorCategoryOverlayDefinition
  * Destiny.Definitions.DestinyVendorCategoryEntryOverlayDefinition
  * (btw I had to have this one explained to me, apparently its some kind of inheritance?)

I might endeavour to rename for the Unofficial wiki pages like this just as I'm not sure how useful C# code references are, especially to people that have never written in C#.

[lowlines]

I tried putting this into practice and didn't like the look of it. My approach instead is grouping components into 5 categories; Definitions, Enums, Classes, Lists/Arrays, Dictionaries. This way I can truncate the names per category rather than trying to find a middle ground that works for all of them.

[vthornheart-bng]

Yeah, that + was a stupid construct - I was nesting classes within each other. There was really no need for me to be doing that, so I'm pulling them out of that nesting.

For DestinyItemComponentSet, the reason why that one looks so odd is that it's a generic type that can use different types of numbers as identifiers for the dictionaries contained within.

(for instance, the DestinyItemComponentSet returned in GetProfile and GetCharacter are int64: it's using instanceIds as keys for all but one of the dictionaries. In the theoretical-but-not-yet-existing GetVendors endpoint, DestinyItemComponentSet will be returned, but with dictionaries keyed by int32: because the items a Vendor sells doesn't have Instance IDs, but we can identify them uniquely by the vendorItemIndex!)

I like the renaming approach you mention here, though I think when it comes to the generic types it's nice to have all of the generic types defined. In the spirit of that, I think I'd do as above but alter the Dictionary responses to be something like (to use your example):

DestinyCharacterDictionaryComponentResponseKeyedByInt64

... it's extremely verbose, but at least then the special characters are removed and it retains all of its generic type information.

Thoughts?

[vthornheart-bng]

(side note, fixed the original URL issue just now, next time I upload it'll be fixed)

[vthornheart-bng]

Cool, grab latest and I've done that renaming. I took a bit of a lazier path, but it all ends up being the same.

Basically, for classes with generic arguments it now uses the form "____Of___And___And___" (not that anything has more than 2 generic arguments, but theoretically if it did it would). That way we retain all the generic argument info in the name without having C# specific symbolic conventions.

[lowlines]

Might have to keep this discussion ongoing. SgtFrankieboy reckons it makes it harder to generate classes now and should be built for machine to parse not a human to read. I do admit Object more visually structural once you have a better understanding of generics, but it just doesn't look like proper formatting to me. Is there like another project made with OpenAPIs on this scale with generics that we can compare to to see how they are doing these component types? I reckon the first priority should be following the standard first with extensions added on for places it lacks.

I'm about to try implementing a component type detector by purely looking at the properties so I'll see how I go with that. Either option probably still isn't ideal, but if the group consensus is making it better for machines to parse, then making it human readable can be something that's done when generating docs rather than modifying the actual spec or something.

[lowlines]

Hmm so like looking at DestinyItemComponentSetOfint32 there is nothing in its properties that specify it is an int32.

"DestinyItemComponentSetOfint32": {
        "properties": {
          "instances": {
            "x-destiny-component-type-dependency": "ItemInstances",
            "$ref": "#/components/schemas/DictionaryComponentResponseOfint32AndDestinyItemInstanceComponent"
          },
          "objectives": {
            "x-destiny-component-type-dependency": "ItemObjectives",
            "$ref": "#/components/schemas/DictionaryComponentResponseOfint32AndDestinyItemObjectivesComponent"
          },
          "perks": {
            "x-destiny-component-type-dependency": "ItemPerks",
            "$ref": "#/components/schemas/DictionaryComponentResponseOfint32AndDestinyItemPerksComponent"
          },
          "renderData": {
            "x-destiny-component-type-dependency": "ItemRenderData",
            "$ref": "#/components/schemas/DictionaryComponentResponseOfint32AndDestinyItemRenderComponent"
          },
          "stats": {
            "x-destiny-component-type-dependency": "ItemStats",
            "$ref": "#/components/schemas/DictionaryComponentResponseOfint32AndDestinyItemStatsComponent"
          },
          "sockets": {
            "x-destiny-component-type-dependency": "ItemSockets",
            "$ref": "#/components/schemas/DictionaryComponentResponseOfint32AndDestinyItemSocketsComponent"
          },
          "talentGrids": {
            "x-destiny-component-type-dependency": "ItemTalentGrids",
            "$ref": "#/components/schemas/DictionaryComponentResponseOfint32AndDestinyItemTalentGridComponent"
          },
          "plugStates": {
            "x-destiny-component-type-dependency": "ItemPlugStates",
            "$ref": "#/components/schemas/DictionaryComponentResponseOfuint32AndDestinyItemPlugComponent"
          }
        }
      },

I can see the issue Frankie was talking about now since changing the Schema URLs will actually break any code that uses them to extract information when that information should property be set as properties so they will always be there while the Schema URLs are evaluated. For you to recreate what was in the schema URL by looking at its properties. We think maybe reverting them back to DestinyItemComponentSet might be better for now in the short term, but also looking at adding maybe more extensions.

So for DestinyItemComponentSet

"DestinyItemComponentSet<int32>": {
    "properties": {
        ...
    }
    "x-generic-type": {
        "type": "integer",
        "format": "int32"
    }
}

This way even if the Schema URLs change, it's not going to have an impact on generating the generic classes for it.

I'm unfamiliar with generics so I'm kind of in between trying to understand it myself but also think about others like me who look at it and go WTF?

[lowlines]

The other idea is rather than having multiple versions of the same class, just have the one and specify the generic properties where it is getting referenced.