v3.0 spec file is extending Reference Objects

[vpzed]

Per the OpenAPI v3.0 spec posted for Reference objects: "This object cannot be extended with additional properties..."

However this is being done quite a bit in the current spec file version like this example where the x-destiny-component-type-dependency property is in the Reference object.

"DictionaryComponentResponseOfint64AndDestinyCharacterComponent": {
  "properties": {
     "data": {
        "type": "object",
           "additionalProperties": {
              "x-destiny-component-type-dependency": "Characters",
              "$ref": "#/components/schemas/Destiny.Entities.Characters.DestinyCharacterComponent"

[vthornheart-bng]

Hmm, it looks like reference objects are the only ones that can't do it, but I'll give it a look: in the example that you give, it's not terribly helpful having that metadata there. It'd be more helpful in the class that refers to DictionaryComponentResponseOfint64AndDestinyCharacterComponent.

If we do end up with locations where this extra metadata is genuinely useful but it's attached to a reference, I would defer to the remainder of that sentence " and any properties added SHALL be ignored." I'm fine with it if standard parsers ignore it, as long as it's there for custom parsers that understand the contextual meaning of x-destiny-component-type-dependency and other extension properties. If it breaks standard parsers, that's something else... but if they're obeying the "SHALL be ignored" part, then I won't lose sleep over breaking with their standard in a way that they ignore.

[lowlines]

Having these also made it a lot easier to add Bungie API specific metadata to the wiki builder. Otherwise I'd probably have to do a bit more regex to pull this information from component urls or other places (which as we found out with the generics stuff, caused some issues for custom parsers).

[vthornheart-bng]

A question before I go about changing this - is it actually causing failure in any existing parsers? According to the spec, it's being ignored... I'd actually rather leave it if it's useful to people and not causing parser tools to fail.

[vpzed]

As I mentioned in another issue there isn't an official "the law" json schema for v3. In the meantime the Google Gnostic team has made this one which is what some preliminary parsers are using (and how I found this item).

The json schema definition there has this which shows additionalProperties: false - but again it isn't official so I'd say it is your call until the official json schema is released for v3. It could go either way with the current wording.

"reference": {
  "type": "object",
  "description": "A simple object to allow referencing other components in the specification, internally and externally.  The Reference Object is defined by JSON Reference and follows the same structure, behavior and rules.   For this specification, reference resolution is accomplished as defined by the JSON Reference specification and not by the JSON Schema specification.",
  "required": [
    "$ref"
  ],
  "additionalProperties": false,
  "properties": {
    "$ref": {
      "type": "string"
    }
  }
},

[vthornheart-bng]

Hmm - let's table it for now then until we get the official ones. It's so convenient, I'm going to keep my fingers crossed. :)