New type system should be expressible in simplified YAML-based syntax

[usarid]

It should be very easy to express structural constraints on data in a YAML-based syntax that fits with the rest of RAML.

For example:

#%RAML 1.0
title: My API with Types
mediaType: application/json
types:
  Person:
    type: object
    properties:
      firstname: string
      lastname:  string
      title?:    string
  Phone:
    pattern: ^[0-9()-]+$
  Manager: 
    type: Person
    properties:
      reports: Person[]
      phone:  Phone
  Admin:
    type: Person
    properties:
      clearanceLevel:
        enum: [ low, high ]
  AlertableAdmin:
    type: Admin
    properties:
      phone: Phone
  Alertable: Manager | AlertableAdmin
  Org:
    type: object
    properties:
      onCall: AlertableAdmin
      [role]: Person
    example: |
      {
        "onCall": 
        {
          "firstname": "Stan",
          "lastname":  "Nicholas",
          "title":     "DBA Lead",
          "phone":     "415-555-1212"
        },
        "Head": 
        {
          "firstname": "Jen",
          "lastname":  "Smith",
          "title":     "Regional VP",
          "reports": 
          [
            {
              "firstname": "Bob",
              "lastname":  "Graves"
            },
            {
              "firstname": "Mara",
              "lastname":  "Burns"
            }
          ]
        }
      }
/orgs/{orgId}:
  get:
    responses: 
      200:
        body:
          application/json:
            type: Org

[lowema]

I like this, will it be available in the parser at all so we can do checks for validity in our code ?

[usarid]

Yes, the new parser will of course support this and all other RAML 1 features -- and BTW it will also support RAML 0.8. The version string (#%RAML 0.8 vs #%RAML 1.0) will tell it which to use.

[freddrake]

This will be absolutely essential for some organizations to adopt RAML; the more concise expression allowed by dropping the JSON syntactic barrier will make it more friendly for many back-end developers.

[vanDonselaar]

I don't see how thing become 'more friendly' for back-end developers by replacing an official draft standard like JSON Schema with a roll-your-own schema syntax. The development of a schema standard is a huge task and you will need to write your own code generators for various languages. Will the YAML based syntax produce both JSON schemas and XML schemas? Or will these things be removed from the standard? Don't feel offended, but it sounds to me like 'not invented here'. Shouldn't we start with things like better support for authentication methods, headers and cookies in the RAML spec? That is the core of a programming interface. Structural constrains are important too, but after all it's just the payload.

[freddrake]

My understanding was that this is a syntactical transformation to make it easier to write and embed JSON Schema inside RAML, but that wasn't stated clearly (neither what the new system by the MuleSoft crew nor my assumption).

I'd be happy with a YAML syntax applied to JSON Schema with a clearly defined mechanical transformation to produce JSON Schema from the YAML syntax (similar to Relax NG and the RNC compact syntax).

This avoids creating a new schema system, which shouldn't be a goal. Continuing to support embedded JSON Schema or XSD would be ideal, though I'd avoid them myself.

[sichvoge]

@vanDonselaar Don't worry - JSON, XML, and all the other types you might want to use are still supported. We don't "drop" or "remove" them from the specification. The new type syntax makes the definition of your models and everything else such as uriParameter, header, etc. simpler and more consistent in the specification. But you are free to use JSON and XML w/o limitations as well.

[vanDonselaar]

Thanks for the clarification @sichvoge @freddrake. Sounds good.