Novice-friendly terminology and complexity

[ProLoser]

I realize it may be too-little, too-late or I may just not be knowledgable enough to speak on this subject, but I've just spent several hours poring over the 0.8 and 1.0 specs for RAML after starting a new job this week (never heard of RAML before) and have found a lot of the terminology used somewhat confusing and at the documentation can be quite self-referencing (making the barrier of entry ridiculously high).

I feel I'm finally starting to come around to understanding things, but I've just been wondering if you guys would be open to consider using a slightly more approachable terminology so that it's easier to adopt RAML.

If I am incorrect about any of my suggestions or understandings of RAML concepts in my proposals below, I would only submit that as evidence as the superfluous complexity of the syntax language

For instance:

Extensions

Why not use the OOP equivalent of extending or extends instead of things like masterRef? You could call these BaseDefinitions (or BaseSchemas or structures or iunno).

Overlays

Are these interfaces? Can't we just call these an interface? Or use an implements keyword?

Traits

These are not that bad, but I'd probably throw around terms like mixins or partials? Iunno, I guess almost anything could be a partial.

ResourceTypes

I mean, these feel like I'm either extending a resource type or mixing in a resource type? Do they really need to be a distinct object? Why can't you just reuse the terminology around extensions or includes or overlays and just provide some examples that says "Hey, you can put any block of raml into an !includeable file that can then be merged with your own overriding inline raml, and here's a commonly used situation in which you would do so: [block of raml traditionally defining a resource type]"

Libraries

Why is an explicit type/object/abstraction even necessary for these? It just seems like a package, but we've got so many packages... I'd rather see us drop some of the types of packages. It seems superfluous when you could just provide some instructions to create a file like:

#%RAML 1.0
!include securty.raml
!include types.raml

And just let people include that file ^ at the top level of their document?

The sheer variety of partials

I'm curious if it's even really necessary to build these explicitly distinct types. SecuritySchemes, Overlays, Extensions, Traits, Libraries, etc.

In a nutshell, you're just including sub-blocks of yaml or merging blocks of yaml together. Why do these even need to be explicitly defined in your docs? Why not simply allow including or merging anywhere?

[ProLoser]

@usarid et all: I am playing around with the api and was trying to leverage DataTypes. I noticed that the documentation here: http://apiworkbench.com/docs/ has a datatype of pet, and then another datatype of mammal and then another of a bird. Each one refers to the parent by it's type property, which is a bit confusing (since we have types, datatypes, and just a plethora of type-things).

What do you guys think about reusing the extends syntax inside of datatypes to specify their parent types? I feel like if anywhere in the spec you would want to emulate OOP, it would be inside of the objects that most closely mirror OOP business objects and classes which extend one another.

A bird datatype extends a mammal datatype which extends a pet datatype.

[ProLoser]

What do you guys think about changing usage inside of libraries to description? Since it's essentially a description, and to me it seems creating more variations or synonyms for similar concepts is unnecessary and creates a bigger API surface area and more specification people must memorize.

[sichvoge]

I agree that changing usage to description would make sense and is more descriptive; at least to me. Lets wait if more people have something to say here.

[sichvoge]

What do you guys think about reusing the extends syntax inside of datatypes to specify their parent types? I feel like if anywhere in the spec you would want to emulate OOP, it would be inside of the objects that most closely mirror OOP business objects and classes which extend one another.

I can't agree here. You actually define the behaviour to inherit properties by declare to be of a specific type when defining the type of a data type. For me at least, that is much more convenient as using extends. I don't think we should replicate what OOP did one by one and stick with simple mechanism to define data types w/o more boilerplate.