[RAML 1] Annotation Type Ownership

[blakeembrey]

How would one go about verifying that an annotation in a RAML document is from an annotation I created as a third-party? For example:

I am writing an API client generator and want to provide a library of annotations types that I use in a "standardized" way. One of these annotation types is called methodName and is of type string. To use this, I import the annotations types into my document and start typing:

uses:
  client: !include ../node_modules/raml-generator/annotations.raml

Now, I've added method names to my API (perhaps in an overlay file) and want to generate the API client. How does the client generator library know that the annotation belongs to the library? There's some possible approaches:

Naive:

The library just checked that the annotation type ends in methodName. For example: /(?:^|\.)methodName$/.test(annotationName).

Pros:

• No additions needed

Cons:

• Name collisions

Prescriptive:

As the library author, I tell you that you must import it using a specific name. E.g. uses: ⏎client: !include ... (must be called client in this case).

Pros:

• Simple

Cons:

• Feels aggressive, results in popular libraries trying to take simple names and leaving late-comers behind - only pushed name collisions down a level

Location:

As a library author, I tell you that you must import from my library. The module checks the location of the original annotation type and uses that as the identifier. E.g. annotation.getLocation() === join(__dirname, '../annotations.raml').

Pros:

• Most unique, no namespace collision possible

Cons:

• The location must match, you can't mix and match someone else's annotations (or your own from a different location)

[sichvoge]

How does the client generator library know that the annotation belongs to the library? There's some possible approaches

Not really understand what you mean?

[blakeembrey]

What part doesn't make sense? Take this example:

uses:
  client: !include ../node_modules/raml-generator/annotations.raml
  otherlibrary: !include ../someotherlibrary/annotations.raml

/users:
  get:
    (client.methodName): getUsers
    (otherlibrary.methodName): Hello World

How does one know which method name is mine (as in, from the client generator)? Is this seen as an issue?

[ddenisenko]

Well, this question basically has two different aspects: parser one and spec one.

Parser aspect: how to know which file annotation comes from. This is doable right now, but is not lying on a top-level. First you need to find annotation declaration one way or another. Will be simplified at Monday release when each annotation reference will have a method returning related annotation declaration node (one of the obvious benefits of having full-functional AST compared to the old JSON that we can actually provide that kind of functionality). Then, having annotation declaration node at hands you may descend to its low-level and ask a unit and its path thus identifying the path, the file comes from. If this is something, which will be often needed by the users, we may consider exposing this functionality at top-level.

Spec aspect: you have file path. Does this allow library identification? I don't think so. Besides file paths we have no real way of library identification right now. This is something purely spec-related.

[ddenisenko]

Summarizing the wall of text above: 1) now you can find, which file annotation belongs to, in several calls. Soon it will be easier, can be simplified even more if needed. 2) File path is the closest thing we have to library identifiers. Introducing real identifiers is better, requires spec change.