search

raml-org / raml-tck

Test Compatibility Kit for RAML 1.0
http://raml-org.github.io/raml-tck/
8 stars 10 forks source link

The TCK should be able to represent RAML objects, not RAML documents. #13

Closed dmartinezg closed 8 years ago

dmartinezg commented 8 years ago

The top level object describing a RAML should not be a document, maybe a specification or api.

Reference: https://github.com/mulesoft-labs/raml-tck/blob/master/Examples/RAML10/Annotations%20002/api-tck.json#L2

ddenisenko commented 8 years ago

I guess this place suites well for a name of the root node. Which can be api, library, or any other type of a fragment. Overlays and extensions too.

sichvoge commented 8 years ago

That is actually a good point Denis. @svacas and @dmartinezg please bear in mind that RAML 1.0 defines fragments that could be either an API, Library, or others. How would you describe that? Should we have the fragment name as root element or the root element is fragment and then metadata about the type of this fragment?

sichvoge commented 8 years ago

We don't have this restriction on 0.8 though. Do we have another root element for 0.8, or do we design it to be similar?

KonstantinSviridov commented 8 years ago

Aggree with @ddenisenko.

dmartinezg commented 8 years ago

document suits well for a DOM, but not for serializers/converters, which may not treat a document at all, only a data structure.

sichvoge commented 8 years ago

@dmartinezg can you elaborate your last comment a bit more; my guess is that document was introduced since we always/usually talking about RAML document.

@KonstantinSviridov can you explain what the rationality was to call it document?

@dmartinezg @blakeembrey what about over fragments? does the root element name mandate what fragment you just parsed? are we only considering Api fragments?

KonstantinSviridov commented 8 years ago

@sichvoge No rationality. As the TCK JSON has two root nodes: one for errors and one for content, we needed some name for the one with content, and I decided to tace "docoument". I think, Denis is right: it must be api, extension, overlay, library or fragment depending on sort of content.

sichvoge commented 8 years ago

or maybe we stick with one and have additional metadata that identifies the object? i think it will be very hard to not have a consistent root element in terms of navigating through the object, but I can be wrong here. Just want to discuss possible downsides :)