Comments (9)
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.
from raml-spec.
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.
from raml-spec.
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... ;-)
from raml-spec.
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 ...
from raml-spec.
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?
from raml-spec.
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 [email protected] 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.
from raml-spec.
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.
from raml-spec.
+1
from raml-spec.
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.
from raml-spec.
Related Issues (20)
- Minor issues in RAML 1.0 doc HOT 1
- RAML 1.0.1 patch
- Ramm
- [Question] How to specify a facet for a nullable type?
- date/time types need support for a sysdate or now default value.
- Add ability to have constants
- Resource parameter default values
- Resource Parameter Conditional Processing
- Clarification on 'type' facet usage HOT 1
- What is the raml code for this? Students: [ { Name: Amritha } { Name: Anagha } ] HOT 1
- Proposal: support type-specification on ?merge tags? (e.g. like {traitName: {<<!string tagName>>}})
- api-model.json is too big in size almost 9 MB HOT 1
- Ambiguous/wrong example of union in Query String section HOT 1
- Change default branch from master to main as per new Guidelines HOT 1
- OAuth 2.0 - Showing 'accessTokenUri: the value has invalid scheme'
- Ability to define wellknown objects in RAML HOT 1
- A reusable 'pageable' trait that can allow reuse of query parameters and result
- HATEOAS isn't explained in the docs or tutorials
- Security Scheme not found when included inside a Library
- AVRO Logical Types must be separate schemas HOT 1
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from raml-spec.