Schema's are first class elements within rAML but Example's are not, this doesn't allow defining examples anywhere but in the Resource so Schema and Example code can never live side by side unless both inlined. As shown in the answer of the Stack Overflow post YAML anchors can be used to reference the Example but it still must be defined within the Resource. This doesn't allow clean separation of the API structure and data definition within the rAML document and is somewhat inconsistent IMHO. Allowing all data definitions, Schemas and Example, to be defined side by side outside of a Resource or even within a different file would allow cleaner and more consistent readability.
Making Example's first class elements and allowing them to be referenced similar to how Schema are is one possible solution. Some new container element to allow specifying anchors as mentioned in the SO post by Amr Mostafa is another.
svacas
commented
9 years ago
This issue stems from http://stackoverflow.com/questions/24297204/how-do-you-reference-example-request-body-in-raml/25057093.
Schema's are first class elements within rAML but Example's are not, this doesn't allow defining examples anywhere but in the Resource so Schema and Example code can never live side by side unless both inlined. As shown in the answer of the Stack Overflow post YAML anchors can be used to reference the Example but it still must be defined within the Resource. This doesn't allow clean separation of the API structure and data definition within the rAML document and is somewhat inconsistent IMHO. Allowing all data definitions, Schemas and Example, to be defined side by side outside of a Resource or even within a different file would allow cleaner and more consistent readability.
Making Example's first class elements and allowing them to be referenced similar to how Schema are is one possible solution. Some new container element to allow specifying anchors as mentioned in the SO post by Amr Mostafa is another.