Defining a model after the reference, and using references in code blocks.

[ecordell]

Right now, it seems that:

• Models must come before they are referenced
• Models cannot be referenced in some contexts, specifically code blocks.

The first just seems like a bug (maybe it's an issue with protagonist?), since the references seem based on MultiMarkdown's references, which I think can be defined after they are referenced.

The second is an enhancement (split this into two issues?). I'm not sure how much is handled by snowcrash specifically and how much is standard multimarkdown, but being able to reference Models in code blocks could save a ton of typing. Or more generally, a simple macro system would be very useful.

[zdne]

@ecordell

Both of your observations are indeed correct and, at this moment, intentional. The concept of models and referencing is at this moment rather sparse. Also is worth to note that Snow Crash is not using any MultiMarkdown parser; instead it just "borrows" the concept of referencing from MultiMarkdown to reference models.

I would like to address the former issue – the need forward definition in near future. As for referencing models in context of another model I am still looking for the best take on it. Please refer to the Embedded assets issue at API Blueprint. Any thoughts and remarks are highly appreciated!

[zdne]

Leaving the Embedded Assets aside I am still not convinced that there is the need to be able to reference models before there were defined.

Can you provide an example? Also I believe @netmilk might have one.

In either case this would lead to a change of the API Blueprint Specification - Resource Model Section so better discuss it amongst API Blueprint issues as strictly this is not a bug in the Snow Crash.

[ecordell]

My concerns are pretty much covered by the embedded assets and data dictionary issues.

What spurred this was simply that I'm dealing with a huge API, will close to 200 endpoints and some responses that are quite large. Our blueprint file is ~7k lines right now and that's with roughly half of the endpoints missing example payloads, and the majority missing schemas. I thought being able to separate the payload models from the actual structure of the API would make it more readable and manageable.

But I think there are plenty of possible solutions floating around on the API Blueprint Spec, so I'll go ahead and close this. Thanks!

[zdne]

@ecordell

Understood. These needs have to be addressed. I believe what we are discussing in #57 will help.