Use YAML syntax to express JSON schemas

[dmartinezg]

As JSON has a 1-1 mapping to YAML, RAML should take advantage of this to simplify the writing of JSON schemas, by allowing them to be written in YAML instead of JSON.

The following examples, should be semantically identical:

#RAML 1.0
title: My sample API
bodies:
  user:
    schema:
      type: json-schema/draft-04
      definition: 
        id: http://my.sample.api/user-schema
        $schema: http://json-schema.org/draft-04/schema#
        type: object
        properties:
          name: {}
        required:
          - name
      objectIdentifier: http://my.sample.api/user-schema

#RAML 1.0
title: My sample API
bodies:
  user:
    schema:
      type: json-schema/draft-04
      definition: |
        {
            "id": "http://my.sample.api/user-schema",
            "$schema": "http://json-schema.org/draft-04/schema#",
            "type": "object",
            "properties": {
                "name": {}
            },
            "required": [ "name" ]
        }
      objectIdentifier: http://my.sample.api/user-schema

[scordatura]

1. Can we save the schema in a separate file and pull it into the RAML with an !include?

If so, do we name it user-schema.yml rather than user-schema.json?

2. Can we use JSON schema references in our schemas?

If so, what would this reference (which is in JSON schema draft 04) look like in YAML?

"address":{"$ref":"jsdb:address#"}

[cybertk]

Could you have a look at csonschema, it's more simpler than vanilla YAML.

[usarid]

csonschema does look simpler, though a lot of questions arise: does it cover all of JSON Schema draft 04? Does it have more docs? Is there any more information you can share about it and about who's behind it?

There are still a lot of advantages in my mind about sticking to JSON Schema as is, with all their power, and simply expressing them in a less crufty way but that maps 1:1 with them.

On Thu, Oct 16, 2014 at 10:20 AM, Quanlong notifications@github.com wrote:

Could you have a look at csonschema http://csonschema.org, it's more simpler than vanilla YAML.

— Reply to this email directly or view it on GitHub https://github.com/raml-org/raml-spec/issues/116#issuecomment-59397477.

[usarid]

1. Yes, in fact that's true of 0.8 too. You can name it what you wish.
2. That seems to be addressed by https://github.com/raml-org/raml-spec/issues/109

On Tue, Oct 14, 2014 at 6:11 PM, Abraham Raher notifications@github.com wrote:

1. Can we save the schema in a separate file and pull it into the RAML with an !include?

If so, do we name it user-schema.yml rather than user-schema.json?

2. Can we use JSON schema references in our schemas?

If so, what would this reference (which is in JSON schema draft 04) look like in YAML?

"address":{"$ref":"jsdb:address#"}

— Reply to this email directly or view it on GitHub https://github.com/raml-org/raml-spec/issues/116#issuecomment-59144152.

[cybertk]

@usarid csonschema just let you write jsonschema with simpler method(cson/YAML), it likes coffeescript vs javascript. csonschema itself is just a compiler, compiles into jsonschema.

[usarid]

I get it, thanks, I'm just wondering about all those other aspects I asked about. On Oct 16, 2014 6:18 PM, "Quanlong" notifications@github.com wrote:

@usarid https://github.com/usarid csonschema just let you write jsonschema with simpler method(cson/YAML), it likes coffeescript vs javascript.

— Reply to this email directly or view it on GitHub https://github.com/raml-org/raml-spec/issues/116#issuecomment-59454486.

[cybertk]

@usarid it covers all aspects of jsonschema draft 4. As I told to @nohorbee before, we provide AaaS(API as a service), including reusable APIs components, automated generated client SDKs, automated API testing, automated generated server, API documents hosting, etc. And parts of them are open-sourced, see raml.link, csonschema.org, abao, ramlev

PS: we already integrated csonschema into RAML 0.8, see this RAML file, in case of RAML 1.0. I think it should be

#RAML 1.0
title: My sample API
bodies:
  user:
    schema:
      type: csonschema
      definition: |
        name: 'string'

[vlcinsky]

@cybertk I like the concept of csonschema. Anyway a bit more details about the format and some sort of specification would help adoption.

Ideally, csonschema should have

• version assigned
• possibly some identifier of format/version in the structure
• specification written and published

See my proposal of supporting wider range of schemas in #117 , if csonschema is included in adopted schema types, you have csonschema supported in whatever parser decides to do so.

[vlcinsky]

@dmartinezg Very good idea - YAML can make JSON schemas much easier to read and maintain.

Basic use case seem to be easy

• inline JSON structure expressed as YAML
• simple !include for one YAML file (which does not include other files).

Couple of complex questions come with trying to use include from within JSON schema. If we want use include inside of externalized JSON schema expressed as YAML file.

One would exect, JSON schemas in form of yaml files would be converted to JSON incl. that extension. For example trang is handling this excellently when converting RELAX NG compact schema into XML one.

In RAML there could be a concept of pre-processor, which would try to convert files into another format. This would require:

• place to define rules for one type of pre-processor
• mapping from source to target file extensions
• some means to specify, which files are to be pre-processed. Minimal solution would use reserved file extensions, rich one would allow adding tags to files marking them as source for pre-processing.

btw: pre-processor solution would work for csonschemas too.

Anyway, support for basic scenarios would be great help for authoring and maintaining RAML specs.

[robertlevy]

+1. migrating from swagger to raml and this is the main thing i miss

[robertlevy]

@vlcinsky - I'd actually like it to come through as a normal object rather than a JSON string. As an object, RAML tools can validate it and we can do fancy things with it in generators. If a generator wants to take the object and spit it out as a string that's fine but the real magic will come when generators can provide the same level of awesome for request/response bodies as they do for query/url/form/header parameters

[holic]

:+1:

[pateketrueke]

+1

[Graham42]

:+1:

[jonathancrosmer]

+1

[sichvoge]

+1, but does still support having pure json schema? people might have existing json schemas they want to re-use. We should be in mind to not restrict people to one format

[sichvoge]

This is subsumed in favour for #167.