apiaryio / api-blueprint-ast Goto Github PK

Note : I know about refract but using JSON AST since refract is still in development.
I am developing an API where it deserializes the JSON ast generated from drafter using jackson. I'm having an issue at deserializing polymorphic subtypes present in "content property" of Element Object.
Actually the drafter generated JSON AST for Element Object is wrong. It should be as

{
      "element": "category",
      "attributes": {
            "name" : "element object"
      }
     "content": [
      {
             "element" : "datastructure",
             "attributes": {
                  "name" : "Datastructure Object"
             }
             "content" :  {
                     DATASTRUCTURE OBJECT HERE
             }
      },
      {
             "element" : "resource",
             "attributes": {
                  "name" : "Resource Object"
             }
             "content" :  {
                     RESOURCE OBJECT HERE
             }
      }
  ]
}

instead of

{
      "element": "category",
      "attributes": {
            "name" : "element object"
      }
     "content": [
         {
               DATASTRUCTURE OBJECT HERE
         },
         {
               RESOURCE OBJECT HERE
         }
  ]
}

In Element Object if element property is of "category enum", content property should be List

AST contains the symbol name in payload.reference.id only when the payload is a reference.

Resource and Action - bound header collections will be deprecated / removed in Format 1B.

Remove the respective header fields entries for resource and action sections.

For a possible future development a serialized parameter value entry should be an object (hash) instead of just a textual value.

E.g.:

From (v1.0):

    parameters: 
      - name: "<name>"
        description: "<description>"
        type: "<type>"
        required: "<required parameter flag>"
        default: "<default value>"
        example: "<example value>"
        values: 
          - "<element>"

To (v2.0):

    parameters: 
      - name: "<name>"
        description: "<description>"
        type: "<type>"
        required: "<required parameter flag>"
        default: "<default value>"
        example: "<example value>"
        values: 
          - value: "<enum element>"

This will enable future non-breakign changes in values enumeration format such as adding description of an enum element.

Hey guys,

This is more of a suggestion or rfc rather than an issue. I have started working on a tool (or a series of tools if all goes well) that use the AST (from drafter.js) to do some interesting things.
When trying to understand the structure of the AST I found the duality of the term element really confusing and I think it could be easily fixed.
So first of all one of objects of the AST is called Element, and then secondly that objects includes a property called element describing the type of the element. I think it would be much more descriptive if the property was actually called type bringing this in line with general programming nomenclature.
If that was the case, my Go code instead of this:

type Element struct {
    Element string `json:"element"`
    ...
}

would look like that:

type Element struct {
    Type string `json:"type"`
    ...
}

This feels so much cleaner and more descriptive to me.

What do you think?

Hi, In the new released format 1A8 it's possible to add attributes to, for example, a request. I don't see this in the example JSON formatted AST, and also I don't see my defined attributes after using Protagonist. Is this feature already implemented?

Presently the parameter object contains these properties. Would be more clear if there is another property which describes where the parameter is actually used like whether it is " form" or "body" or "query" parameter etc.

The API Blueprint spec allows for enumerated values of parameters to each have a description:

+ <parameter name>: `<example value>` (<type> | enum[<type>], required | optional) - <description>

    <additional description>

    + Default: `<default value>`

    + Members
        + `<enumeration value 1>` - <enumeration description 1>
        [...]

The AST, however, exposes the enumeration value, but not the description:

Properties
* [...]
* values (array) - An array enumerating possible parameter values
  * (object)
    * value (string) - Value choice of for the parameter

I'd expect that the description should also be provided in the AST. Without it, the documentation cannot show the description provided in the API Blueprint doc.

Proposed change as posted originally at apiaryio/snowcrash#60:

(breaking change)

Use ordered arrays instead of maps

In order to preserver ordering of headers, metadata and parameter keys in various settings and languages the following changes are needed:

• Metadata object use ordered array instead of a map
• Headers object use ordered array instead of a map
• Parameters object use ordered array instead of a map

From (v1.0):

metadata:
  <key>:
    value: <value>

To (v2.0):

metadata: 
- name: "<metadata key name>"
  value: "<metadata value>"

From (v1.0):

"metadata": {
  "<key>": {
    "value": "<value>"
  }
},

To (v2.0):

"metadata": [
  {
    "name": "<metadata key name>",
    "value": "<metadata value>"
  }
],

Same change applies to headers and parameters objects.

Up to this point this change does affects serialized AST media types only. It does not affect the actual AST structure as defined and used within the Snow Crash.

Don't know if I mentioned this before, but

• defining one (1) model per resource seems reasonable
• defining one (1) pack of headers and body per model isn't

1 Resource -> ~1 Model -> n Representations {ContentHeaders, Body}

Hi

When will Resource Groups (now deprecated) be removed from the spec?
I noticed it's still used a lot throughout the open-source community, so I assume it will be for version 1B?

Michiel