WORK IN PROGRESS
The following Typescript file will serve multiple purposes ( in order of importance ):
- Enable Typescript tools to consume the output of the raml-js-parser in a type-safe manner
- Provide an additional source of documentation for developers trying to get their heads around the RAML spec
- Move towards a canonical javascript/json representation for RAML that other Javascript based tools can support
Considering the above, some comments to keep in mind:
- The starting point for this definition is highly influenced by the output of the pre-existing JS parser ( remember goal N1 ). We will probably be able to influence its design in future iterations as we move towards goal N3.
- The official RAML Spec is the only authoritative source
- Not every possible clever refactoring or Typescript idiom will be used ( to achieve goal N 2 )
Challenges
- YAML and JSON are differnet. This will leak
- Even if we define one canonical RAML model for JSON, there will always be at least 3 different models in reality:
- Complete/Strict model - ex: the output of parsing a valid RAML file
- Incomplete model - ex: the output of parsing a RAML file which is being edited ( by a parser that supports this kind of use case )
- Complete + Interpretation - The fully expanded model ( with resource types and traits interpreted )
- Read the source for now. Suggest edits, etc.
- RAML is complex enough to require some advanced Typescript concepts that didn't make it to 1.3 ( Type Aliases and Union Types )
- If you are in a hurry, check out the pre-release of the CATS IDE
