Suggesting namespace annotation
#3
Conversation
|
Can you remove this iml file, please. |
removing intelliJ iml.
|
You don't need a gitkeep file right? Do you think we will add more domain description annotations? If yes, I'd suggest to move them into a dedicated folder |
|
Removed
At some moment for sure. However I have a following concern with placing This annotation has very simple semantic which may be used without going deep into describing domain. For example simplest use case is that some may just assign some unique namespace for his annotation types), so I am not sure that this annotation should in Personally for me it is a more like a core annotation which should be promoted to be used by any annotation library author to identify his libraries. In other words it is related to domain but I am not sure that we should place it inside of domain folder. So it might be that something like @antoniogarrote what do you think? |
|
@antoniogarrote @sichvoge pinging you |
libraries/namespaces.raml
Outdated
| description: | | ||
| this annotation type allows you to associate unique identifier with a RAML document. | ||
| type: string | ||
| (namespace): http://raml.org/vocabularies/annotations/core |
There was a problem hiding this comment.
I have some doubts about the value for the annotation:
- In general it could be any unique string, but that's difficult to enforce.
- We could try to specify that it should be a URL, but that mean we are enforcing the idea of RAMLs as linked data. This is not something clear right now. For example, Exchange doesn't share it.
- It could be a URI, as the (http://raml.org/vocabularies/annotations/core or exchange:group.asset.version)
- It could be a URI prefix, like (http://raml.org/vocabularies/annotations/core#)
Should we specific about this?
Is there a way of being more specific than just saying type: string?
There was a problem hiding this comment.
Agree with Antonio. We shouldn't use a string.
There was a problem hiding this comment.
Also, let's move that under a core directory.
There was a problem hiding this comment.
There is the thing in question here actually. If we do not want to use string should we enforce uri's or uri prefixes. I personally would prefer to enforce uri's.
But this actually enforces some naming scheme that might be not optimal for some approaches.
For example if Exhange guys would generate this annotations for their assets, they might probably want to have namespace value looking as java package name.
So I decided to leave it as string for now, and then when we have a decition, we may issue version 2 of this library.
There was a problem hiding this comment.
On other side if we all agree that uri's is the way to go let's just define an uri type.
There was a problem hiding this comment.
So as well as I can guess you are voting for explicitly requiring it to be url. (As for me I am almost 100% sure that it should be urls, but probably would prefer to write this in comment for this version of the library)
Do we have a type uri already or do you need to define it?
I have this type in other library which I am not contributing yet. Do you think that we should include it to this PR?
Regards,
Pavel
There was a problem hiding this comment.
Not really sure what you mean. Can you elaborate, please?
There was a problem hiding this comment.
Not really sure what you mean. Can you elaborate, please?
The global goal of this annotation is to solve identity problem for reusable artefacts in RAML. Solving this goal does not strictly require us to add any restrictions on the identifier
values , we can require it to be an uri or url or just leave it as string. By some reason I have misread you and thought that you are suggesting it to be urls which looks like to restrictive at this stage.
My suggestion was to let it be a string with a comment in the initial version, and then when we gather more feedback, release a next version which will contain stricter restriction.
Only concern that I have agains making it an uri in a first version it that it might affect some theoretical naming schemes that people may want to use.
Regards,
Pavel
There was a problem hiding this comment.
Not sure if "making it more restrictive" is the best approach. That would potentially mean that specs that using this annotation might fail. This would be a breaking change. Why are we not making it restrictive now and if use cases come in that need a bit more flexibility, we open it? This way we would not break existing specs.
There was a problem hiding this comment.
That would potentially mean that specs that using this annotation might fail
Not actually, because specification depends from some fixed version of the library.
Why are we not making it restrictive now and if use cases come in that need a bit more flexibility, we open it?
Already agreed and changed to uri. :-)
|
@petrochenko-pavel-a I agree this is really core. In fact it should even be part of RAML itself. We are encouraging people to build modules, but they cannot name those modules. We have problem with identity in RAML that has to be solved before the release of Exchange 2.0 These are all the different ways we are trying to solve the question of how to identify a reusable unit of a RAML spec:
The only important thing is the plain label of the re-used annotated domain element (annotation type, type, trait, etc). The document where the element is included is not important, it doesn't provide a namespace.
Namespace is not explicit. The published document (URL) is implicitly the namespace for the elements in the document. Logical namespace and physical HTTP URL are the same thing.
The namespace is explicit but it's stored in project descriptor using Maven (GAV) syntax and only important to resolve dependencies by an external package manager.
Makes the namespace explicit. Provides a stable namespaced identity to every single element of the spec independently of where is located (local file, URL) or how the file was retrieved. We need to find some agreement around this different approaches, and that should happen before customers start creating lots of re-usable units in Exchange 2.0 |
At some moment it was... :-) As well as I understand AMF is fine with namespaces, so as for me what we should do is to try to convince people in exhange to support namespaces in some form, however I do not see any blocker for us here. |
|
Added url and uri types, added requirement for namespace to be an uri |
Hi guys, this PR is a result of today raml-dialects meeting.
As we all agree we need an annotation to associate a global identifier with a document. It is very likely that this identifier should be an url, but for now we are only sure that this annotation should exists and agreed about common name for it.
P.S. As for me it seems that we should require that value of this annotation should be a valid url. (we are not sure in this yet, so I am not adding this into PR itself)
P.P.S Another question is what are allowed valid targets for this annotation, as for me it should be any RAML fragment.
At this moment we use this both in AMF and in my research projects, so it would be nice if we will be able to standardise it.