In an API Blueprint document, can I combine a model with headers?

Question

The “model” facility seems intended to reduce duplication — when specifying the requests and responses to various methods on a resource, the same body will frequently be specified multiple times. So one can define a “model” and then “refer” to it within various request and response “payload” sections.

So I’ve defined a model like so:

### An Event

* Model (application/vnd.document+json)

            {
                "_type": "document",
                ...
            }     

and I can then refer to it in various places:

* Response 200

    [An Event][]

which works great; the output includes the entire model body in place of the cross-reference.

However, I can’t figure out how to combine this reference with a request or response header.

I’ve tried various formats along these lines:

* Request

    * Headers

            If-Match: some-etag-value

    * Body

            [An Event][]

or

* Request

    * Headers

            If-Match: some-etag-value

    [An Event][]

with no luck.

Is there any way to do this?

Answer 1

There is currently no way to alter referenced model's payload. Neither it's planned in any of API Blueprint Milestones.

Feel free to add it to the milestones and propose its syntax, if you will. Before doing so please consider any potential synergy with planned API Blueprint Object Traits.