Expanded Type Form

[antoniogarrote]

Different users of RAML types have different (and usually opposed) of describe the information of the type at the syntactical level.

Users authoring RAML documents would favor:

• compact and expressive syntax (like type expressions)
• avoid redundancy using libraries etc

Tools processing type information would prefer:

• consistent output, information should always have the same format
• autonomous and complete information, so everything can be processed locally

Right now, different tools provide different outputs for the same input type. This makes thing really hard for authors of tools. The problem is that the input syntax allows multiple ways of expressing the same schema and there's no standard output syntax defined.

I would like to define a common syntax aimed at tools processing and consuming type information so it's easier to work with RAML types.

Ideally this syntax should:

• expand all type expressions
• expand all user defined type names by there representation
• flatten inheritance relationships

The output should be a canonical, flatten, standalone representation of any schema that can then be processed in a standard way by any tool.

The spec should ideally define an algorithm to achieve this expanded form, dealing with the ambiguities that might appear, like resolving inheritance relations.

An example of what I'm suggesting, can be found in JSON-LD API spec, where algorithms to arrive to an expanded, compacted and flattened forms are defined. Normal flow working with JSON-LD is to fetch the data and then run expansion before processing the data.

Some examples:

types:
  A:
    type: object
    properties:
      a: string
  B:
    type: array
    items: integer
  C:
    type: object
    properties:
      c: B[]
  D:
    type: [A,B]
    properties:
      d: integer
#...
my_thing_with_schema:
    type: D

After parsing that input, when exposing the type of my_thing_with_schema to other tools, the type should be represented in this expanded form:

type: object
properties:
  a: string
  c:
    type: array
    items:
      type: array
      items: integer
  d:
    type: integer

This representation of the type is unambiguous, and contains all the information required to work with the schema. Having such a representation would make the life of tools authors much easier and would also be useful for a different number of tasks, like defining a standard mapping between RAML and other formats like JSON-Schema.

[sichvoge]

I completely agree that there should be an option on normalizing data types and a description inside the specification on how to achieve that. I wonder how that would work for type expressions like [ Cat, Do, Cat | Dog, Person ].

In addition to that, if people do not want to nomalize and preserve all type information (eg for documentation) we need to at least normalize type expression and everything that has two meanings. For example:

type: Bank[]

should be normalized into

type: array
items: Bank

That helps tools that needs to process these information to have a consistent model that they need to handle. Probably, for all that we should create another issue. Comments?