Api-blueprint: Unable to reference Data Structure object within array

[pete001]

Hi there, thanks for such an awesome product!

I am documenting using JSONAPI format, and i am having an issue with expressing an object within an array. This is required due to the JSONAPI spec for non-empty to-many relationships.

Here is my example code:

# Group Stock
All inventory information and management is exposed through the `stock` endpoint.

## Stock [/stock/{id}]

- Parameters
    - id: 1 (number, required) - Specific `id` of a stock item

- Attributes (Stock Base)
    - id: 1 (number) - Specific id of a stock item
    - type: stock (string) - Resource type

### Retireve Stock [GET]
Fetch details about specific stock.

- Response 200 (application/vnd.api+json)
    - Attributes (Stock)

## Stocks [/stock]

- Attributes
    - data(array[Stock]) - Full output of all data

### List all Stock [GET]
Return details of all stock.

- Response 200 (application/vnd.api+json)
    - Attributes (Stocks)

# Data Structures

## Stock Base (object)
- price: 4.50 (number) - Standard price
- sale_price: 3.00 (number) - Specific sale only price
- description: Coconut yoghurt (string) - Text description of stock item
- ingredients: Coconut, Nuts, Milk (string) - Comma separated list of all ingredients
- allergens: Nuts, dairy (string) - Comma separated list of all allergen information
- Include Stock Links Base

## Stock Links Base (object)
- links (object) - JSON API links section
    - *dietary_requirements* (array)
        - Include Linkage
    - *stock_type*
        - Include Linkage

## Linkage (object)
- linkage (object) - JSON API linkage section
    - id: 1 (number)
    - type: reference_type (string)

If you render this in apiary, you will notice that the dietary_requirements array is empty, even though it references the Linkage Data Structure.

Any help would be much appreciated.

[kylef]

Try changing this:

- *dietary_requirements* (array)
    - Include Linkage

To this:

- *dietary_requirements* (array[Linkage])

I don't believe it's possible to use mixins (include) with arrays like in this example.

[pete001]

Wow, totally amazing! Thanks so much for the speedy response, this worked perfectly :smile:

[zdne]

@kylef is correct – Include is meant to work with objects only (spec).

However the parser should warn on this occasion – isn't this the case? //cc @pksunkara

[zdne]

@pete001 also you can specify any type as a content of array like so:

- my_array (array)
    - (type1)
    - (type2)
    - (another type)

[pete001]

Thanks @zdne! The apiary parser wasnt complaining at me, was validating ok.

[pksunkara]

The parser should give a warning. Let me check.