Define syntax for deep linking to elements within a RAML file

When writing Markdown documentation within a RAML document it should be possible to refer to elements. For example, the following is a documentation snippet from the Twitter API:

place_id:
  description: |
    A place in the world. These IDs can be retrieved from GET geo/reverse_geocode.

This is quite common.

I propose we define a syntax for linking to elements within a RAML spec. Documentation generators can then generate the appropriate links and named anchor tags to enable navigation where appropriate.

Links are not the only way to extract value from these annotations. Tooltips with contextual reference also become possible.

As an example, imagine if we could do the following:

place_id:
  description: |
    A place in the world. These IDs can be retrieved
    from [GET geo/reverse_geocode](#get/geo/reverse_geocode).

That's not too hard is it? And well worth the effort.

This is just to get the conversation started and put this out there before 1.0 is finalized. Here are other things to consider:

Should we link all the way down to parameters? By reading the docs I have realized that references to parameters are prevalent as well. Actually, they may be even more prevalent than references to methods. And they are evidently valuable.
And if we link to parameters. Why not other elements? If we generalize too much we would end up defining something like RAML-path. How far should we go? Is there a simple way of getting to an 80/20?
A RAML-path syntax should be expressive and obvious to use based on the structure of the document. ( which structure? the pre-interpreted structure? Good question )
The simplest path syntax only requires a descendant operator character. This is enough to "access" maps ( via keys ) and sequences ( via index ). We can't use dots or slashes. ( since they are valid parts of keys ). If we used a double slash, the following would be a path /resource//get//queryParameters//name
We should define a subset of elements that are "linkable". Not all of them should be linkable. But at the very least resources, methods and params should be ( and params occurring in headers, query, forms, etc ). Also. What if you link to a trait? It makes sense if, for example, you are talking about "paging" within the documentation. But that would force generators to expose traits in a more direct manner. So, yeah. We may choose to limit this at first, but linking to normal methods and parameters is definitely easy and valuable.

raml-org / raml-spec

Define syntax for deep linking to elements within a RAML file #128