Ability to select a particular sample of a referenced name type

[jmdacruz]

I recently found myself in the following situation: I defined a couple of Named Type objects, one referencing the other(e.g., object A has a reference to object B). Each of the objects may have a couple of Sample sections. I'd like to have the ability, when defining the Sample section of object A, to reference a particular Sample in object B's definition. This would allow me to document difference scenarios of the API.

Moreover, I'd like to see Samples that are just instantiations of the type definitions, or that are somehow validated against the type definition (in order to avoid inconsistencies between samples and the type definition)

[pksunkara]

This is something we have been thinking about but the MSON feature is still in beta and we would like to finish supporting it first.

[jmdacruz]

Sounds good! Just wanted to get it on your radar.

I think it will become an important feature over time, as people start using Apiary for emulating different sample outputs using the "Prefer" header (which I think it's a very powerful feature). Developers using the "Prefer" header in combination with complex (e.g., nested) objects won't be able to use MSON because of the limitation I've documented in this issue (the alternative would be having different Named Types for each sample, which defeats the purpose of using MSON)

[zdne]

or that are somehow validated against the type definition (in order to avoid inconsistencies between samples and the type definition)

This is definitely planned for a future release of the parser.

As for the referencing one sample from another – I do not really see a use as for it. Maybe an example would help?

Note, in MSON, there is nothing like type definition and instantiation – those two are essentially a the same.

Isn't something like:

# Data Structures
## A (object)
+ a1: 1
+ a2: 2

# Resource A [/a]
## Create [GET]
+ request (application/json)
  + attributes (A)

+ response 201

+ request (application/json)
  + attributes (A)
    + a2: 42

+ response 400

working for you?

Note this is related to apiaryio/api-blueprint#58 (when it comes to specifying what is a response based on input properties)

[jmdacruz]

I see... so you basically try to instantiate the attributes at the Resource, when you are instantiating the data structure. I tried with the blueprint below, but it's not working for me (let me know if there is something wrong with it...)

FORMAT: 1A
HOST: http://parametrizedmson.apiblueprint.org/

# Testing parametrized MSON

Just testing parametrized MSON.

# Resource A [/a]
## Create [GET]
+ request (application/json)
  + attributes (A)

+ response 201

+ request (application/json)
  + attributes (A)
      + a2: 42

+ response 400



# Data Structures
## A (object)
+ a1: 1
+ a2: 2

Comments and questions:

• If you try to render the blueprint, you'll see that for the 400 response you'll get a parameter table with 3 parameters instead of two (with a2 having a value of 42). This is what I get:

Name	Type	Required	Description	Value
a2	optional	42
a1	optional	1
a2	optional	2

• I would expect the parameter table for response 400 to show just one instance of a2 with a2 => 42, and also that the example POST payload shows 42 as the value for a2
• Assuming the example works: What would happen if Data Structure A had a nested reference to a Data Structure B defined separately? What I'd like to do with this you propose is to be able to parametrize attributes on the Request section that would affect both Data Structure A and Data Structure B
• Moreover, imagine that A is an item and B includes a collection of As:

# Data Structures

## Item (object)

### Properties
- uuid: `08ff7052-2e95-11e3-a1fc-000c294eede0` (required, string, sample) - A unique ID
- property1: 42
- property2: 56

## Collection (object)

### Properties
- data (object, required, sample)
    - currentItemCount: `1` (required, number, sample) - Number of items in the current view of the collection
    - totalItems: `1` (required, number, sample) - Number of total items in the collection
    - items (array[Item])

• In the data structure above, how would I be able to create parametrized instances of Collection where I can define different values for the Item values in the array?
  • Same question would apply if instead of a nested array you just have a reference to a different data structure

[pksunkara]

Hey @jmdacruz

Regarding the a: 42 not overriding the a: 2, it is an known bug and we are working on it. But other than, your 2 other feature requests are good and we will be looking into them. Thanks.

[jmdacruz]

Great to now! Thanks!

[zdne]

@pksunkara is there a tracking issue for the "a: 42 not overriding the a: 2" ?

[pksunkara]

hmm... Looks like we don't have a tracking issue for it.

[zdne]

@pksunkara so please create one or turn this one into it (but preferably the former and on the parser). Thanks!

[zdne]

If we do not have a tracking issue then it is not a know issue :)

[pksunkara]

apiaryio/drafter#44

[zdne]

thanks @pksunkara

[zdne]

Just to reiterate. Is there another issue but the fix of apiaryio/drafter#44 .

@jmdacruz are we looking for a way to display different samples in libraries using MSON or are we asking parser – representation renderer to render specific sample instead of the default one?

[pksunkara]

From what I understood, @jmdacruz was talking about having a way to select a specific sample to be sent the to the renderer in certain cases instead of the default one.

Example (disregard the syntax): We have a named type User with samples describing users pavan and kyle.

+ (array)
    + (User:pavan)
    + (User:kyle)

should render the following:

[
  {
    "username": "pavan"
  },
  {
    "username": "kyle"
  }
]

[jmdacruz]

@zdne can you elaborate on the difference between these two alternatives?

are we looking for a way to display different samples in libraries using MSON or are we asking parser – representation renderer to render specific sample instead of the default one?