It'd be nice if we could specify json-schemas as structured data

[radix]

Since json is a subset of YAML, it would be nice if we could specify the json schemas in-structure with the RAML. These two examples would become possible:

/{songId}:
  get:
    body:
      application/json:
        schema: {
          "$schema": "http://json-schema.org/schema",
          "type": "object",
          "description": "The canonical song representation",
          "properties": {
            "title":  { "type": "string" },
            "artist": { "type": "string" }
          },
          "required": [ "title", "artist" ]
        }

(Notice the lack of the | in the schema object)

Or, more interestingly,

/{songId}:
  get:
    body:
      application/json:
        schema:
          $schema: "http://json-schema.org/schema"
          type: "object"
          description: "The canonical song representation"
          properties:
            title:
              type: "string"
            artist:
              type: "string"
          required:
            - "title"
            - "artist"

This would allow the json-schema to "fit in" better with the RAML schema, in addition to making available the use of things like !include for subsections of a json-schema. Just an idea!

[idris]

I could maybe see an argument for the first proposal. As for the second, the JSON schema is already a defined spec, and it is defined as JSON, not YAML, so having a YAML version of it could be problematic, especially since YAML is a superset of JSON.

[radix]

I'm not sure if I explained the idea correctly. There aren't actually two proposals; both of those examples are identical -- a YAML parser will produce the same exact output for both, which would be a nested structure in the "schema" key instead of a big string.

I'm not proposing a "YAML version" of json-schema, exactly. If I am, I'm only proposing a syntax facade for the identical structure -- it should not be an extension in any way. I believe most json-schema libraries work with structured data anyway, not json strings (or if they do, they parse the strings and then deal with the structure). I'm not sure exactly what would be problematic. Are you concerned that people would try to put non-json-compatible structures in the schema? If so, it would be in error.

Anyway, it's just an idea. I prefer structured data instead of unstructured strings, and it would be nice if my RAML file could be entirely YAML.

[usarid]

RAML does indeed allow inline schema definitions, it's just that their values are strings, as far as RAML (and YAML) are concerned, not structured data. The following is valid:

#%RAML 0.8
title: A one-song API
/{songId}:
  get:
    body:
      application/json:
        schema: |
          {
            "$schema": "http://json-schema.org/schema",
            "type": "object",
            "description": "The canonical song representation",
            "properties": {
              "title":  { "type": "string" },
              "artist": { "type": "string" }
            },
            "required": [ "title", "artist" ]
          }

Note the pipe symbol, which allows spanning a string scalar across multiple lines. The reason for this direction was to accommodate multiple schema types, for now JSON and XML schemas. JSON schemas can indeed be represented in YAML, though YAML would then permit adding more to them that would no longer be permitted in JSON, to @idris point that YAML is a superset.

But it's really true that JSON schema have not taken off with anywhere near the popularity of JSON itself. In speaking to many venues, very few people have ever really used JSON schemas for anything. So at some point we need to address that, either by making JSON schema more palatable, or by moving to something else, and if that happens to be made simple and readable and writeable like we did in RAML using YAML, well... ;-)

[maryoush]

I would really see this as the important feature. Starting from that this will allow to build/compose schema nest them and make them parameterized to avoid code duplication ...

[usarid]

Since today the value of the schema property is a string and hence could be invalid JSON already, seems there's no harm in moving to YAML structures for this and for JSON examples. We could even say that whenever the value of schema or of example is a non-scalar, it must be interpreted as JSON.

What do you think of simultaneously moving to JSON Schema draft 4 while we're at it?

[maryoush]

I eagerly waiting for it. We found it very convenient to have some possibility to aggregate bigger schema from smaller chunks. I think keeping compatibility only for schema version 3 now is not an option now.

Wysłane z iPada

Dnia 10 lut 2014 o godz. 16:36 Uri Sarid notifications@github.com napisał(a):

Since today the value of the schema property is a string and hence could be invalid JSON already, seems there's no harm in moving to YAML structures for this and for JSON examples. We could even say that whenever the value of schema or of example is a non-scalar, it must be interpreted as JSON.

What do you think of simultaneously moving to JSON Schema draft 4 while we're at it?

— Reply to this email directly or view it on GitHub.

[emcpadden]

I am currently looking into using RAML for a Mulesoft Anypoint API Proof of Concept and I too would love to see a way to compose a response schema from other schemas.

I did a previous proof of concept using Swagger on the Apigee platform and in general, i really like RAML much better with the exception that Swagger allowed you to compose the schema for the responses. The down side with Swagger is that it all has to be in the same swagger file.

I notice that the last comment on this is from Feb 2014, is this being pursued?

I'm for anyway that would allow a response schema to be composed from multiple schemas.

[zontafil]

+1

[sichvoge]

Thats being covered with the RAML data type system. Have a look https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md#raml-data-types.